Introduction to the Fork Workflow

Basic Concepts of the Fork Workflow

The Fork Workflow is one of the most common collaboration processes in Git, particularly suitable for open-source projects or team development. It allows contributors to participate in project development without directly modifying the original repository. Each developer maintains their own remote repository copy (fork), where they can make independent changes and then submit modifications to the original repository via Pull Requests (PRs).

The core principles of this workflow are:

• Each developer maintains their own remote repository copy
• Code review and merging are conducted through the Pull Request mechanism
• The original repository (upstream repository) remains clean, with only reviewed code being merged

Detailed Steps of the Fork Workflow

1. Fork the Remote Repository

First, fork the original repository to your own account on a code hosting platform (e.g., GitHub, GitLab):

# After clicking the "Fork" button on GitHub, clone your repository copy
git clone https://github.com/your-username/project.git
cd project

2. Add the Upstream Repository

To stay synchronized with the original project, add the original repository as an upstream remote:

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

3. Create a Feature Branch

Never develop directly on the main/master branch. Instead, create a separate branch for each new feature or fix:

git checkout -b feature-branch

4. Commit Changes

Develop on the feature branch and commit changes:

// Example: Modifying frontend code
function newFeature() {
  console.log('Implementing new feature');
  // New feature implementation
}

git add .
git commit -m "Implement new feature"

5. Push Changes to Your Remote Repository

Push the local branch to your forked remote repository:

git push origin feature-branch

6. Create a Pull Request

On the code hosting platform's interface, initiate a Pull Request from your feature branch to the original repository's main branch.

Keeping Your Fork Synchronized

Since the original project is continuously updated, regularly synchronize your fork:

# Fetch upstream changes
git fetch upstream

# Merge into the local main branch
git checkout main
git merge upstream/main

# Update the remote fork
git push origin main

Resolving Conflicts

When the upstream repository changes and your branch is based on an older version, you may need to resolve conflicts:

# Fetch the latest changes from upstream
git fetch upstream

# Rebase on the feature branch
git checkout feature-branch
git rebase upstream/main

# Continue rebasing after resolving conflicts
git add .
git rebase --continue

# Force-push the updated branch
git push -f origin feature-branch

Advanced Workflow Techniques

Using Multiple Remotes

For complex projects, you may need to interact with multiple remote repositories:

# Add a colleague's fork as a remote
git remote add colleague https://github.com/colleague/project.git

# Fetch the colleague's changes
git fetch colleague

Interactive Rebase

Organize commit history before submitting a PR:

git rebase -i HEAD~3  # Organize the last 3 commits

Using Pull Request Templates

Adding a .github/PULL_REQUEST_TEMPLATE.md file can standardize PR descriptions:

## Change Description

## Related Issue
Fixes #123

## Testing Instructions
- [ ] Tested Feature A
- [ ] Tested Feature B

Team Collaboration Best Practices

1. Small, Granular Commits: Each PR should address only one issue or implement one feature.
2. Clear Descriptions: PR descriptions should detail the changes and their rationale.
3. Code Reviews: At least one core maintainer must approve before merging.
4. CI Integration: Ensure all tests pass before merging.
5. Branch Cleanup: Delete remote feature branches after merging.

Handling Common Issues

Addressing Rejected PRs

# After making changes based on feedback
git add .
git commit --amend  # Amend the last commit
git push -f origin feature-branch  # Force-push updates

Extracting Specific Commits from Other Branches

git cherry-pick commit-hash  # Extract a specific commit to the current branch

Reverting Faulty Merges

git revert -m 1 merge-commit-hash  # Revert a merge commit

Automation Tool Integration

Modern code platforms offer many automation features:

# Example GitHub Actions configuration
name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - run: npm install
    - run: npm test