Section 6 Git Hub Feature Branches

6.1 When to Use a Feature Branch

Working in a feature branch is similar to working in a forked repository, except you have two parallel workflows with varying commit history in the same [forked] repository. Use a feature branch when:

  • You have a lot of changes but want to make a small pull request.
  • You’re doing a PR review that requires running code.
  • You have a separate part of the project you want to store separately.
  • You’re working on an exploratory or separate task and don’t want to affect your main branch – maybe you’ll end up discarding it.
  • You want to check for merge conflicts before pushing.
  • You are working on a very specific issue or feature that is independent of others’ work on the repo – or even your other branches!
  • You want to continue working on a codebase while other code is in review.

IMPORTANT: Try not to leave your branches unmerged for long periods of time if other folks are working in the same repository, to help alleviate merge conflicts.

6.2 How to Create and Work with Feature Branches

6.2.1 Step 1: List Existing Branches and Remotes

Before creating a branch, check what already exists:

git branch -v          # list local branches
git remote -v          # list existing remote connection (i.e., git repos you can pull files in from)

6.2.2 Step 2: Add a Remote (if needed)

If the remote you want to branch from isn’t already listed (e.g., for a PR review of someone else’s fork):

  • Go to the GitHub page and copy the SSH or HTTPS link.
  • Add the remote (because you want to branch to it):
git remote add new_remote_name ssh_link
# or
git remote add new_remote_name https_link
  • Fetch the remote to see its contents (does not download files yet):
git fetch new_remote_name

To remove a remote you no longer need:

git remote delete remote_name

6.2.3 Step 3: Create or Switch to a Branch

Create a new branch from a remote branch:

git checkout -b new_branch_name remote_name/branch_name

Switch to an existing branch:

git checkout branch_name
# or
git switch branch_name

Create a new branch starting from the current branch:

git checkout -b new_branch_name

The branch starts as a copy of whichever branch you were on, unless you specify a branch to originate from, like shown above. If you switch back to main using git checkout main, your branch work will appear to disappear – fear not, it’s still there on the feature branch.

6.2.4 Step 4: Make and Commit Changes

Add and commit as usual within your branch:

git add .
git commit -m "some changes to this branch"

6.2.5 Step 5: Push or Merge Your Branch

Push the branch to your remote (forked repo):

git push -u origin new_branch_name

Merge branch changes back into main:

git checkout main
git merge new_branch_name

You can also submit a pull request from your feature branch the same way you would from your main branch. Just make sure you’ve selected the correct branch from your forked repo.

6.3 Making a Smaller PR from an Existing Branch

Sometimes you want to make a PR that starts from where the central repository (upstream) is, rather than your full main branch. This is useful when you have a lot of local changes but want to submit only specific files.

# Create new branch "pr" from upstream/main
git checkout -b pr upstream/main

# Then selectively add files from your main branch:
git checkout main .gitignore _targets
# or
git restore --source main -- file_name

6.4 Merging Branches

Merge combines two branch histories, keeping the most recent commit from each file and joining the two timelines into one.

git merge branch_name
# example:
git merge experiment

Tip: If you get stuck in a merge review in the terminal with no obvious way to exit, type :q and press Enter.

6.5 Moving Work from a Feature Branch to Main

Say you worked on an “experiment” branch and want to bring some or all of that work into your main branch:

  1. Make sure all changes are committed on your current branch. 2. Create (or switch to) the experimental branch: bash git checkout -b experiment
  2. Make changes and commit: bash git add . git commit -m "some changes to this branch"
  3. Bring changes into main:
    • Update just one file in main: bash git switch main git checkout experiment file_to_checkout
    • Merge all changes from “experiment” into current branch: bash git merge experiment

6.6 git checkout vs. git merge

checkout: Use to bring in a file from another branch. If the file already exists, it overwrites local changes with the new checked out version. It does not combine histories.

merge: Merge can be used to combine two branches or individual files from two branches. It will combine with rules for keeping most recent commit from each file, joining the two histories into one.

git checkout git merge
Use for Bringing in a specific file from another branch Combining two full branches
If file exists Overwrites local changes with the checked-out version Combines with rules for keeping the most recent commit
History Does not combine histories Joins two histories into one

6.7 Deleting a Branch

Once a branch is no longer needed:

git branch -D branch_name

6.8 Note, this permanently deletes the branch. You CANNOT retrieve it from your local device. If and only if you pushed the most recent changes to origin will you be able to restore any changes from this branch.

6.9 Feature Branch Best Practices

  • COMMUNICATE with your team.
  • Keep your fork up to date regularly.
  • Each team member should work on separate files/features (no overlap; feature collaboration can take place in pull requests).
  • Don’t leave branches unmerged for long periods when others are active in the repository.