Debugging a Missing README: A Git Branch Management Case Study

How a Simple GitHub Display Issue Revealed Deeper Architectural Decisions in a Full-Stack Application

When working with modern full-stack applications, sometimes the most seemingly simple issues can lead to profound learning experiences about architecture, version control, and deployment strategies. This article documents a real-world debugging journey that started with a missing README file on GitHub and evolved into a comprehensive exploration of Git branch management, CI/CD pipelines, and architectural decision-making.

The Initial Problem: A Tale of Two Realities

The issue began with a puzzling discrepancy. I thought I successfully created and pushed a comprehensive README.md file to a GitHub repository, complete with project documentation, setup instructions, and architectural diagrams. I even saw detailed evidence of the success, showing Git commit hashes and push confirmations. Yet when viewing the repository on GitHub's web interface, the main page still displayed the generic "Add a README" message, suggesting no documentation existed.

This contradiction between what I saw locally and what GitHub displayed presented an interesting debugging challenge. In development, when two systems disagree about the state of data, the truth usually lies in understanding how each system views that data differently.

The Diagnostic Approach: Systematic Investigation

Rather than making assumptions or immediately attempting fixes, the debugging process began with systematic investigation. The first step was understanding the current state of the local repository compared to what GitHub was displaying.

Step 1: Verifying Local Git State

The investigation started with examining the current branch and synchronization status:

git status --short --branch && echo "---" && git log --oneline -5 --graph --all --decorate

This compound command revealed crucial information. The output showed that work was being conducted on a develop branch, which had successfully received the README commit. The commit hash 1f95592 with the message "docs: add comprehensive README for PCVN ERP system" existed and had been pushed to the remote develop branch. This confirmed that I had indeed created and committed the file, but raised the question of why it wasn't visible on GitHub.

Step 2: Understanding the Working Directory

A critical discovery came from examining the shell prompt:

lenovo@LAPTOP-3HQ8DPON:~/code/ltphongssvn/pcvn-fullstack/erp-frontend$

The working directory was inside the erp-frontend subdirectory, not the repository root. This observation led to investigating whether the README had been created in the wrong location.

Step 3: Locating the Missing File

To determine where the README actually existed, a comprehensive search was performed:

find .. -name "README.md" -type f 2>/dev/null | head -10

This search revealed that the README.md file did exist in the repository root (../README.md), exactly where it should be for GitHub to display it. This finding shifted the investigation from a missing file problem to a branch visibility issue.

The Root Cause: Branch Divergence

The breakthrough came from understanding GitHub's default branch behavior. When viewing a repository on GitHub's web interface, it displays the contents of the default branch, typically main or master. However, all recent development work, including the README creation, had been committed to the develop branch.

To confirm this theory, the investigation examined what changes existed in develop but not in main:

git log main..develop --oneline --graph && echo "---Files changed---" && git diff --stat main develop

The output revealed fourteen commits in develop that weren't in main, representing substantial changes including:

• Migration from Create React App to Vite build system
• Node.js upgrade from version 18 to 20
• Comprehensive ESLint and Prettier configuration
• Multiple documentation files including the README
• CI/CD pipeline enhancements
• Extensive frontend refactoring

The statistics showed 181 files changed with approximately 36,000 lines added and 23,000 lines removed, representing a major technical modernization effort that had been developed in isolation on the develop branch.

The Solution: Strategic Branch Merging

With the root cause identified, the solution required merging the develop branch into main. However, given the scale of changes, this wasn't a trivial operation. The approach taken demonstrated best development practices.

Testing the Merge

Before executing the actual merge, a dry run was performed to ensure compatibility:

git checkout main && git merge --no-commit --no-ff develop --strategy-option=ours && git status && git merge --abort

This command sequence attempted a merge without committing, showed what would be staged, and then aborted the merge. The successful dry run confirmed that all changes could be merged without conflicts.

Executing the Strategic Merge

The actual merge was performed with a comprehensive commit message documenting the technical milestone:

git checkout main && git merge --no-ff develop -m "feat: Major frontend modernization and documentation update

This merge brings significant improvements from the develop branch:

Frontend Modernization:
- Migrated build system from CRA to Vite for 10x faster HMR
- Upgraded Node.js from v18 to v20 for better performance
- Implemented comprehensive ESLint configuration
- Added Prettier for consistent code formatting

Documentation:
- Added comprehensive README.md for project overview
- Created team onboarding guide
- Documented CI/CD processes and monitoring
- Added checkpoint validation reports

Infrastructure:
- Enhanced GitHub Actions workflows for better CI/CD
- Implemented checkpoint strategy for safe deployments
- Added security scanning workflows
- Optimized Docker configurations for development

Code Quality:
- Extensive refactoring of frontend components for better performance
- Improved TypeScript type safety across the application
- Enhanced error handling and monitoring capabilities
- Added comprehensive test coverage

This represents a major technical upgrade preparing the platform
for scale while maintaining backward compatibility."

Publishing the Changes

The final step was pushing the merged changes to GitHub:

git push origin main

The push succeeded with minimal data transfer (only 965 bytes), as GitHub already had all the file changes from the develop branch. Only the merge commit itself needed to be transmitted.

Lessons Learned: Architecture and Process

This debugging journey revealed several important principles about modern development:

Version Control as Documentation

Git history serves as more than just a backup system. When properly maintained with meaningful commit messages and logical branch structures, it becomes documentation of architectural decisions and project evolution. The merge commit created during this process will serve as a historical marker explaining why such significant changes were consolidated at this point in the project's lifecycle.

Branch Strategy and Visibility

The separation between develop and main branches protected production code while allowing experimental changes to be thoroughly tested. This incident highlighted the importance of understanding which branch is being displayed by default in repository hosting services and ensuring that documentation updates reach the appropriate visibility branch.

Systematic Debugging

Rather than immediately attempting fixes based on assumptions, the systematic investigation approach revealed the true nature of the problem. Each diagnostic command provided specific information that built toward understanding the complete picture. This methodical approach prevented unnecessary work and potential complications from misguided fix attempts.

Technical Debt and Modernization

The scale of changes revealed in the develop branch represented significant technical debt payment. The migration from Create React App to Vite, the Node.js version upgrade, and the comprehensive refactoring all represent investments in the project's future maintainability and developer experience. These changes, while requiring careful management, position the project for better performance and easier maintenance going forward.

Technical Impact and Benefits

The successful merge brought several immediate technical benefits:

Performance Improvements

The Vite migration provides near-instantaneous hot module replacement during development, potentially saving hours of developer time weekly. Where Create React App might take several seconds to reflect changes, Vite updates in milliseconds, maintaining developer flow and productivity.

Enhanced Type Safety

The extensive TypeScript refactoring evident in the changed files improves code reliability and developer experience through better IDE support and compile-time error detection.

Improved Documentation

The addition of comprehensive README documentation, onboarding guides, and CI/CD documentation makes the project more accessible to new contributors and easier to maintain long-term.

Automated Quality Assurance

The enhanced GitHub Actions workflows provide automated testing, security scanning, and deployment validation, catching issues before they reach production.

Conclusion: Beyond the Immediate Fix

What began as a simple missing README investigation evolved into a comprehensive exercise in Git branch management, architectural decision-making, and systematic debugging. The issue wasn't just about making a file appear on GitHub; it was about understanding how modern development practices use branching strategies to manage complexity and risk.

For developers, this experience reinforces several key practices. First, always verify the actual state rather than trusting reported states when systems disagree. Second, understand that Git branches create parallel realities for your code, and visibility depends on which reality you're examining. Third, major technical improvements should be managed thoughtfully, with clear documentation of what changed and why.

The successful resolution not only made the README visible on GitHub but also promoted significant technical improvements to the main branch, documented the project's evolution through meaningful commit messages, and demonstrated best development practices that balance the need for progress with the requirement for stability.

This debugging journey exemplifies the kind of real-world problem-solving that defines best development practices. It's not just about writing code or fixing bugs; it's about understanding systems, managing complexity, and making informed decisions that benefit both immediate needs and long-term maintainability.

This article is part of my debugging case studies series, where I document systematic approaches to solving complex technical problems. Each case study demonstrates not just the solution, but the investigative methodology that reveals underlying system behaviors and architectural patterns.

If you enjoyed this article, you can also find it published on LinkedIn and Medium.