Using git rebase to update your local branch.

1-rebase-to-branch.md

Below is a step-by-step guide (in plain English) for rebasing your feature branch on top of main. The code is purely demonstrative—treat it as a starting point if you want an automated workflow around Git operations.

Tip

There is an attached bash script I call gitru.sh (git rebase update). It automatically rebases your local feature branch (basically it updates your local branch with changes from the main branch). Only run it on separate feature branches avoid running it on the main branch.

---

1. Scientific Method-Inspired Breakdown

1.1 Design Requirements & Use Cases

• You have a feature branch that was originally created off the main branch.
• The main branch has received new commits, and you need your feature branch to include those changes.
• You prefer a rebase so your feature branch’s commits appear on top of the main branch commits, creating a linear history.

1.2 Tools & Equipment

• A command-line interface (CLI) with Git installed.
• Access to the Git repository containing both main and feature branches.
• (Optionally) A Deno environment if you intend to automate any steps with TypeScript scripts.

1.3 Procedure

1. Ensure your local main is up to date:

   git checkout main
   git pull origin main

2. Switch to your feature branch:

   git checkout feature

3. Start the rebase onto main:

   git rebase main

4. Resolve conflicts (if any):
   • Open the files with conflicts.
   • Edit and save the changes (choose what's correct).
   • Stage the resolved files:

     git add <file1> <file2> ...

   • Continue the rebase:

     git rebase --continue

   • If you need to abort the entire rebase, you can do:

     git rebase --abort

5. Confirm your rebase result:

   git log --oneline

   You should see your feature branch commits on top of the updated main commits.
6. Force push (if working on a remote shared feature branch):

   git push --force-with-lease origin feature

   Using --force-with-lease is safer than a raw --force since it won’t overwrite remote work if another user also committed.

1.4 Sample Preparation & Tests

• Test the final state of your feature branch locally to ensure everything still builds and passes tests.
• Optionally create a backup or separate branch (e.g. feature_backup) to avoid losing progress in case of rebase mistakes.

---

2. Example Usage Scenarios

Example 1: No Conflicts

1. You run:

   git checkout main
   git pull origin main
   git checkout feature
   git rebase main

2. The rebase completes automatically (no conflicts), and you see a straightforward updated commit history.
3. You verify the logs:

   git log --oneline

4. You then do:

   git push --force-with-lease origin feature

5. Everything works without manual intervention.

Example 2: Conflicts Present

1. You run:

   git checkout main
   git pull origin main
   git checkout feature
   git rebase main

2. Git reports a merge conflict in src/app.ts.
3. You open src/app.ts, fix the conflict markers (<<<<<<<, =======, >>>>>>>), and save the file.
4. You stage changes:

   git add src/app.ts

5. Continue rebase:

   git rebase --continue

6. If further conflicts appear, repeat the process until done.
7. Finally:

   git push --force-with-lease origin feature

---

Summary

Rebasing your feature branch on top of the main branch is a straightforward process:

1. Make sure main is current.
2. Switch to feature.
3. Execute the rebase.
4. Resolve conflicts if needed.
5. Push your updated branch.

gitru.sh

#!/usr/bin/env bash

# A script to update a feature branch with the latest main changes via rebase.
# If you're on main when running, it will prompt for which branch to update.
# If you're on some feature branch already, it will update the current branch.

# Usage: ./gitru.sh
# (No arguments needed; this script detects your state.)

# Exit immediately on errors, unset variables, or pipeline failures.
set -euo pipefail

# Enable tracing for debugging purposes. Uncomment the following line during development.
# set -x

function error {
  echo "ERROR: $1" >&2
  exit 1
}

# Validate that the script is running inside a Git repository
git rev-parse --is-inside-work-tree > /dev/null 2>&1 || error "Not a Git repository. Please run this script from within a Git repository."

# Ensure the user is on a valid branch and not in a detached HEAD state
if [ "$(git symbolic-ref --quiet HEAD 2>/dev/null || echo detached)" == "detached" ]; then
  error "You are in a detached HEAD state. Please checkout a branch and try again."
fi

# Check if a rebase is already in progress
if [ -d ".git/rebase-merge" ] || [ -d ".git/rebase-apply" ]; then
  echo "A rebase appears to be in progress. Attempting to continue..."
  git rebase --continue || error "Could not continue rebase. Fix conflicts, then re-run."
  echo "Rebase continued successfully. Now pushing changes..."
  CURRENT_BRANCH=$(git branch --show-current)
  git push --force-with-lease origin "$CURRENT_BRANCH" || error "Push failed."
  echo "Done!"
  exit 0
else
  # No active rebase, proceed normally
  CURRENT_BRANCH=$(git branch --show-current)

  if [ "$CURRENT_BRANCH" == "main" ]; then
    # If you're on main, ask for the feature branch name
    echo "You are on 'main'."
    read -rp "Which feature branch would you like to update? " FEATURE_BRANCH
    if [ -z "$FEATURE_BRANCH" ]; then
      error "No feature branch specified."
    fi
    # Validate that the feature branch exists
    git show-ref --verify --quiet "refs/heads/$FEATURE_BRANCH" || error "Branch '$FEATURE_BRANCH' does not exist."
  else
    # If you're not on main, assume the current branch is the feature branch
    FEATURE_BRANCH="$CURRENT_BRANCH"
  fi

  echo "Switching to main..."
  git checkout main || error "Failed to checkout main."

  echo "Pulling latest from origin/main..."
  git pull origin main || error "Failed to pull latest from origin/main."

  echo "Switching to feature branch: $FEATURE_BRANCH ..."
  git checkout "$FEATURE_BRANCH" || error "Failed to checkout $FEATURE_BRANCH."

  echo "Rebasing $FEATURE_BRANCH onto main..."
  git rebase main || {
    error "Rebase encountered conflicts or failed. Fix conflicts and re-run."
  }

  echo "Rebase successful. Now pushing $FEATURE_BRANCH..."
  git push --force-with-lease origin "$FEATURE_BRANCH" || error "Push failed."
  
  echo "Done! Your feature branch '$FEATURE_BRANCH' is now up-to-date with main."
fi