Custom Work with a Public GIT Repo

Notes on using a public git repo and keeping your custom code isolated.

Yes, this was ChatGPT generated then edited - sue me!

Article

When building a project based on an open-source GitHub repository, it's essential to manage your changes effectively while staying synchronized with updates from the original project. Here's a comprehensive approach to achieve this using Git's powerful features:

1. Fork the Original Repository

• Forking¹ creates a personal copy of the repository under your GitHub account. This allows you to freely experiment without affecting the original project.

  Steps:

  • Navigate to the original repository on GitHub.
  • Click the "Fork" button in the top-right corner.
  • Choose your GitHub account or organization where the fork will reside.

^1.If you're using DevOps then import the GitHub repo.

2. Clone Your Fork Locally

• Clone the forked repository to your local machine to start making changes.

  git clone https://github.com/your-username/your-fork.git
cd your-fork

3. Set Up the Original Repository as Upstream

• This allows you to fetch updates from the original repository and integrate them into your fork.

  git remote add upstream https://github.com/original-owner/original-repo.git

  • Verify Remote URLs:

    git remote -v

    You should see both origin (your fork) and upstream (the original repository).

4. Create a New Branch for Your Changes

• Isolate your modifications in a separate branch to keep them organized and to facilitate easier integration with upstream changes.

  git checkout -b my-feature-branch

5. Make and Commit Your Changes

• Develop your features, fix bugs, or make enhancements in this branch.

  # Make changes to files
git add .
git commit -m "Add my feature"

6. Regularly Sync with the Original Repository

• To incorporate updates from the original project, regularly fetch and merge (or rebase) the upstream changes.

  Fetch Upstream Changes:

  git fetch upstream

  Merge Upstream into Your Branch:

  git checkout my-feature-branch
git merge upstream/main

• Alternatively, you can rebase:

  git checkout my-feature-branch
git rebase upstream/main

  Rebasing creates a cleaner history but requires careful handling of conflicts.

7. Resolve Conflicts

• When merging or rebasing, conflicts might arise. Git will notify you of conflicting files.

  • Resolve Conflicts Manually:

    • Open each conflicted file.

    • Decide which changes to keep.

    • After resolving, mark the files as resolved:

      git add path/to/resolved-file

  • Continue the Merge/Rebase Process:

    git commit # If merging
git rebase --continue # If rebasing

8. Push Your Changes to Your Fork

• After integrating upstream changes and finalizing your work, push your branch to your GitHub fork.

  git push origin my-feature-branch

9. Optional: Create Pull Requests

• If you intend to contribute back to the original project, you can open a Pull Request (PR) from your feature branch to the original repository.

  • Navigate to your fork on GitHub.
  • Click on "Compare & pull request".
  • Provide a descriptive title and detailed description of your changes.
  • Submit the PR for review.

10. Best Practices

• Commit Often: Make frequent, small commits with clear messages to track changes effectively.
• Stay Updated: Regularly sync with the upstream repository to minimize merge conflicts.
• Use Descriptive Branch Names: Name your branches based on the feature or fix (e.g., feature/user-authentication).
• Document Your Changes: Maintain clear documentation for your modifications to assist future development and collaboration.
• Test Thoroughly: Ensure your changes don’t break existing functionality by writing and running tests.

11. Advanced Techniques

• Using Feature Flags: Implement feature toggles to enable or disable features without deploying separate codebases.
• Submodules/Subtrees: If your changes are substantial or modular, consider using Git submodules or subtrees to manage dependencies separately.
• Continuous Integration (CI): Set up CI pipelines to automatically test and validate changes when syncing with upstream or when making new commits.

Resources

• GitHub Forking Workflow
• Keeping a Fork in Sync
• Git Branching - Branches in a Nutshell

By following this structured approach, you can effectively isolate your changes, maintain a clean project history, and seamlessly integrate updates from the original GitHub repository. This ensures that your project remains up-to-date and benefits from the ongoing improvements made by the original authors and the community.