Resolve Your First Git Merge Conflict

Trigger and resolve a real Git merge conflict using branches.

Introduction

30 Second Summary

You're working on a team project and you both edit the same file. When you try to combine your work, your version control tool refuses and flags a conflict.

In this project, you will simulate this exact scenario by creating two Git branches that edit the same file, triggering a merge conflict, and resolving it by hand.

What You'll Build

A local repository where you play both sides of a team conflict, resolve it in your terminal, and push clean merged history to GitHub that proves you handled it.

By the end of this project, you'll have:

  • The ability to switch between feature branches from the terminal and watch about.md change instantly in Cursor.
  • A repeatable way to trigger a merge conflict on demand and see Git's conflict markers appear in your file.
  • The confidence to read those markers, resolve the conflict, and complete a clean merge commit pushed to GitHub with full branch history visualized.
  • Secret Mission: Resolve a multi-section conflict where both branches added entirely new content to different parts of the same file.

Are there any prerequisites?

This project assumes you are comfortable with git add, git commit, git push, and creating repositories on GitHub. If you have completed the "Build a Developer Portfolio with GitHub" project, you are ready.

Before We Start

Before we dive in, let's lock in what you're about to build and why it matters.

Set Up Your Repository

Every merge conflict starts the same way: two people change the same file from the same starting point. To simulate that later, you first need a shared starting point.

In this step, you will create a GitHub repository, clone it to your machine, and push an initial file to the main branch. This gives Git a common ancestor to compare against when branches diverge.

In this step, get ready to:
  • Create a new repository on GitHub.
  • Clone the repository to your local machine.
  • Push an initial project file to the main branch.
Create a new repository on GitHub
  • Go to github.com in your browser.
  • Click the + icon in the upper-right corner of the page.
  • Select New repository from the dropdown menu.
  • Enter git-merge-practice in the Repository name field.
  • Keep the Public option selected.
  • Check the box labeled Add a README file.
  • Click Create repository at the bottom of the page.

GitHub redirects you to your new repository page. You should see a README.md file listed in the file browser.

Why initialize with a README?

Checking Add a README file creates an initial commit on the main branch automatically. This means your repository is ready to clone immediately instead of being an empty shell.

Don't see the repository page?

Make sure you are signed in to your GitHub account. If you see a 404 page, double-check that you clicked Create repository after filling in the form.

help me find my new GitHub repository

Clone the repository to your machine

Cloning downloads a full copy of the repository to your computer so you can work on it locally.

  • Switch back to Cursor.
  • Open the terminal by pressing Ctrl+` (macOS) or Ctrl+` (Windows).
  • Clone your repository by running this command:
git clone https://github.com/[[GITHUB_USERNAME="your GitHub username"]]/git-merge-practice.git
  • Move into the project folder by running:
cd git-merge-practice

You should see terminal output from the clone command showing that Git downloaded your repository. Your terminal prompt now shows you are inside the git-merge-practice directory.

Seeing 'repository not found'?

Double-check that the username in the URL matches your actual GitHub username. The repository name must be exactly git-merge-practice with no typos.

If you get a permission error, make sure you authenticated Git with GitHub (using HTTPS credentials or an SSH key).

help me fix a git clone error

Create the project file and push to main

Now you will create the file that both branches will edit later. Having this file on main gives Git the common ancestor it needs to detect conflicts.

  • In Cursor's Explorer sidebar on the left, hover over the git-merge-practice folder name.
  • Click the new file icon that appears.
  • Name the file about.md and press Enter.
  • Paste the following content into about.md:
# About Our Team

We are a small team of developers building open-source tools.
Our focus is on making development workflows simpler and more accessible.

## Team Members

- Alex - Lead Developer
- Sam - Backend Engineer
- Jordan - Frontend Engineer

What is in this file?

This is a simple team description in Markdown format. The exact content matters because both branches will edit the same lines later to trigger a conflict.

  • Save about.md by pressing Cmd+S (macOS) or Ctrl+S (Windows).
  • Stage and commit the file by running these commands in your terminal:
git add about.md
git commit -m "Add initial about page"

Git confirms the commit with a short message showing your commit hash and the text Add initial about page.

  • Push your commit to GitHub by running:
git push

What do these commands do?

  • git add about.md stages the file, telling Git you want to include it in the next commit.
  • git commit -m "..." saves a snapshot of your staged changes with a descriptive message.
  • git push uploads your local commits to the remote repository on GitHub.

Before you run the next command, what do you think git log --oneline will show? How many commits do you expect to see?

  • Verify your setup by running:
git log --oneline

You should see your Add initial about page commit at the top, along with the initial commit that GitHub created when you checked Add a README file.

Don't see your commit?

Make sure you saved about.md before running git add. Unsaved changes in Cursor are not picked up by Git.

If git push failed, check the error message for authentication issues. You may need to set up a personal access token or SSH key for GitHub.

help me troubleshoot my git push

✔️ Awesome, I've got everything!

Great. Double check you have saved about.md and that your git log --oneline output shows your commit.

ⓧ I'd like to double check the full code

Here is the complete about.md file you should have at this point:

# About Our Team

We are a small team of developers building open-source tools.
Our focus is on making development workflows simpler and more accessible.

## Team Members

- Alex - Lead Developer
- Sam - Backend Engineer
- Jordan - Frontend Engineer

Your repository has a solid starting point. Next up, you will create a feature branch and watch how switching branches changes your file content instantly in Cursor.

Create a Feature Branch with Changes

Your repository is set up with about.md committed on main. You now have the shared starting point that branches will build on.

When developers work on a feature, they create a separate branch so their changes stay isolated from the main codebase. In this step, you will create a feature branch, make an edit, and switch between branches to see how Git keeps each version completely separate.

In this step, get ready to:
  • Create a feature branch called update-bio.
  • Edit about.md with a new team description on the feature branch.
  • Switch between branches and watch the file content change in Cursor.
Create and switch to a feature branch

A feature branch is a copy of your project where you can make changes without affecting main. The -c flag tells Git to create a new branch and switch to it in one command.

  • Create and switch to a new branch called update-bio by running this command:
git switch -c update-bio

You should see Switched to a new branch 'update-bio' in your terminal.

What is git switch?

The git switch command is the modern way to change branches. The -c flag is short for --create, so git switch -c update-bio means "create a branch called update-bio and move me onto it."

Seeing 'not a valid object name'?

Make sure you are inside the git-merge-practice folder. Run pwd to check your current directory.

Help me troubleshoot this branch creation error

Make changes on the feature branch

You are now on the update-bio branch. Any edits you make here will not touch main. You will edit the same team description lines you wrote in Step 1.

  • Open about.md in Cursor's editor by clicking it in the Explorer sidebar.
  • Find these two lines near the top of the file:
We are a small team of developers building open-source tools.
Our focus is on making development workflows simpler and more accessible.
  • Replace those two lines with the following:
We are a passionate group of engineers dedicated to open-source innovation.
Our mission is to simplify complex development workflows for teams of all sizes.
  • Save the file.

✔️ Awesome, I've got everything!

Great. Double check you have saved about.md before continuing.

ⓧ I'd like to double check the full code

Your full about.md should look exactly like this:

# About Our Team

We are a passionate group of engineers dedicated to open-source innovation.
Our mission is to simplify complex development workflows for teams of all sizes.

## Team Members

- Alex - Lead Developer
- Sam - Backend Engineer
- Jordan - Frontend Engineer
  • Stage and commit your changes by running these commands:
git add about.md
git commit -m "Update team bio with new description"

Git confirms the commit with a summary showing your branch name and the changes made.

Why does this edit matter later?

You edited the exact same lines that still exist on main. In Step 3, you will go back to main and make a different edit to those same lines. Two branches editing the same lines is what causes a merge conflict.

Commit failed?

If you see "nothing to commit", make sure you saved about.md in Cursor before running git add. Unsaved changes in the editor are not seen by Git.

Help me troubleshoot my commit error

Switch back to main and see the difference

This is where branch isolation becomes real. You are about to switch branches and watch the file content change right in front of you in Cursor's editor.

Before you run the next command, think about this: what do you expect about.md to look like when you switch back to main?

  • Switch to the main branch by running:
git switch main

You should see Switched to branch 'main' in your terminal.

  • Look at about.md in Cursor's editor.

The file shows the original content. Your "passionate group of engineers" edit is gone. It still exists safely on the update-bio branch, but main has no knowledge of it.

  • Now switch back to the feature branch by running:
git switch update-bio

You should see Switched to branch 'update-bio' in your terminal. Look at about.md again. Your updated description is back.

What just happened?

Each branch holds its own version of the file. When you switch branches, Git swaps the file contents on disk instantly. Cursor picks up the change and updates the editor.

This is how teams work in parallel. One developer edits on their branch while another works on theirs, and neither sees the other's changes until they merge.

File not changing in Cursor?

Make sure about.md is saved before you switch branches. If the file has unsaved edits, Cursor may not refresh it with the branch content.

Help me figure out why my file is not updating

You have seen how branches keep work isolated. Each branch is its own version of the project, and switching between them swaps the files instantly. Next up, you will create a competing change on main that sets the stage for a merge conflict.

Create a Competing Change on Main

You have a feature branch with changes that main doesn't know about yet. In a real team, someone else would push their own changes to main while you are still working on your branch.

You are going to simulate exactly that scenario by switching to main and editing the same lines you changed on update-bio. This is what causes branches to diverge, and diverging branches are the recipe for merge conflicts.

In this step, get ready to:
  • Switch to main and edit the same lines that update-bio changed.
  • Commit the competing change on main.
  • Visualize the diverging branch history with a graph.
Switch to main and edit the same lines

Right now you are on the update-bio branch. To simulate a teammate making a competing change, you need to switch back to main and edit the same section of about.md.

  • Switch to the main branch by running this command:
git switch main

Open about.md in Cursor. The file now shows the original content from Step 1, because main hasn't received any of your update-bio changes.

  • In about.md, find these two lines under the # About Our Team heading:
We are a small team of developers building open-source tools.
Our focus is on making development workflows simpler and more accessible.
  • Replace those two lines with a completely different description:
We are a collaborative team focused on building developer tools that ship fast.
Our goal is to reduce friction in the software development lifecycle.

Why different content?

You are deliberately writing something that contradicts the update-bio version. Both branches now describe the team in their own way, but only one version can survive in the final file. Git cannot pick a winner for you, so it will ask you to resolve the disagreement.

  • Save about.md.

✔️ Awesome, I've got everything!

Great. Double check you saved about.md before moving on.

ⓧ I'd like to double check the full code

Your about.md should look exactly like this:

# About Our Team

We are a collaborative team focused on building developer tools that ship fast.
Our goal is to reduce friction in the software development lifecycle.

## Team Members

- Alex - Lead Developer
- Sam - Backend Engineer
- Jordan - Frontend Engineer
Commit the competing change

With the file saved, you need to commit this change on main so that Git records it as a separate snapshot from the one on update-bio.

  • Stage and commit the change by running these commands:
git add about.md
git commit -m "Revise team description on main"

What does this do?

git add about.md stages your edited file, telling Git you want to include it in the next commit.

git commit -m "Revise team description on main" saves a new snapshot on the main branch. Now main and update-bio each have their own commit that changes the same lines differently.

Seeing 'nothing to commit'?

Make sure you saved about.md in Cursor before running git add. Unsaved changes exist only in the editor buffer and Git cannot see them.

help me figure out why Git says nothing to commit

Visualize the diverging branches

Both branches now have commits that the other branch does not. Git tracks this as a fork in history. You can see the fork with a graph view of the log.

Before you run the next command, think about what the graph will look like. Will main and update-bio still be on the same line, or will they have split apart?

  • Visualize your branch history by running:
git log --oneline --all --graph

You will see a forked graph showing main and update-bio splitting from a common ancestor commit. The two tips of the fork represent the two competing descriptions that now exist in parallel.

How do I read this graph?

Each * is a commit. Lines branching apart show where history diverged. You should see one line going to your main commit and another going to your update-bio commit, both connected back to the original Add initial about page commit.

Graph looks like a single line?

If you do not see a fork, double check that you committed on both branches. Run git log --oneline on main and confirm you see the Revise team description on main commit. Then run git switch update-bio and run git log --oneline to confirm the Update team bio with new description commit exists there.

help me figure out why my git log graph doesn't show a fork

Your branches have officially diverged. Main says one thing about the team, and update-bio says another. Next up, you will try to merge them together and watch Git refuse to pick a winner.

Attempt the Merge and Hit the Conflict

Your branches have diverged. Main and update-bio each have their own version of the team description in about.md, and Git has no way to know which one you actually want.

In this step, you will try to merge the two branches together. Git will refuse to do it automatically because both branches edited the same lines. This is the exact scenario that trips up developers in their first week on a team.

In this step, get ready to:
  • Run git merge and see Git refuse to auto-merge.
  • Read the conflict markers Git inserts into your file.
  • Check the repository status to confirm the conflicted state.
Attempt to merge the feature branch into main
  • Make sure you are on the main branch by running:
git switch main

Before you run the next command, pause and predict: do you think Git will merge the two branches cleanly, or will something go wrong?

  • Attempt to merge update-bio into main by running:
git merge update-bio

Git cannot combine the two versions automatically. You will see output that includes:

CONFLICT (content): Merge conflict in about.md
Automatic merge failed; fix conflicts and then commit the result.

This is exactly what is supposed to happen. You just triggered your first merge conflict. Git is telling you it found competing changes to the same lines and needs you to decide what the final version should be.

Why did Git refuse?

Git can merge changes automatically when they happen in different parts of a file. When two branches edit the exact same lines, Git has no way to guess which version you intended to keep.

Instead of guessing wrong, Git stops and asks you to resolve the conflict manually. This keeps your code safe from silent overwrites.

Seeing 'Already up to date' instead?

This means the branches were already merged in a previous attempt. If you need to start fresh, you can delete the local repo folder and re-clone from GitHub, then repeat Steps 2 and 3.

help me reset my repository so I can trigger the merge conflict again

Open the conflicted file and read the markers
  • Open about.md in Cursor's editor by clicking it in the Explorer sidebar on the left.

You will see that Git has inserted conflict markers directly into the file. Your file now looks like this:

# About Our Team

<<<<<<< HEAD
We are a collaborative team focused on building developer tools that ship fast.
Our goal is to reduce friction in the software development lifecycle.
=======
We are a passionate group of engineers dedicated to open-source innovation.
Our mission is to simplify complex development workflows for teams of all sizes.
>>>>>>> update-bio

## Team Members

- Alex - Lead Developer
- Sam - Backend Engineer
- Jordan - Frontend Engineer

What do these conflict markers mean?

  • <<<<<<< HEAD marks the start of your current branch's version (main).
  • ======= separates the two competing versions.
  • >>>>>>> update-bio marks the end of the incoming branch's version.

Everything between <<<<<<< HEAD and ======= is what main has. Everything between ======= and >>>>>>> update-bio is what the feature branch has.

Cursor may show resolution buttons

Cursor may display buttons like Accept Current Change or Accept Incoming Change above the markers. Ignore these for now. You will resolve this manually in the next step so you understand exactly what is happening.

Check the repository status

Git tracks which files have unresolved conflicts. You can confirm the conflicted state by checking the status.

  • Check the current state of your repository by running:
git status

You will see about.md listed as "both modified" under an "Unmerged paths" section. This confirms that Git is waiting for you to resolve the conflict before the merge can finish.

What does 'both modified' mean?

"Both modified" means both branches changed this file in ways that conflict. The merge is paused mid-way. Git will not let you make new commits on this branch until you either resolve the conflict or abort the merge entirely.

You have officially hit your first merge conflict. Next up, you will resolve it by editing the file, removing the markers, and completing the merge.

Resolve the Conflict and Push to GitHub

You triggered the merge conflict and read Git's conflict markers. You now know exactly which lines each branch changed and where they overlap.

In this step, you will edit the file to remove those markers and decide what the final content should be. Then you will complete the merge and push the clean result to GitHub so the merged history is visible to your whole team.

In this step, get ready to:
  • Remove conflict markers and choose the final content for about.md.
  • Complete the merge with git add and git commit.
  • Push the merged result to GitHub and verify the branch history.
Edit the file to resolve the conflict

Resolving a merge conflict means editing the file until it contains exactly what you want the final version to look like. You remove all marker lines and keep, discard, or combine content from both sides.

  • In Cursor, return to about.md where you can still see the conflict markers.
  • Delete all three marker lines: <<<<<<< HEAD, =======, and >>>>>>> update-bio.
  • For the team description, keep the wording from the update-bio branch and combine it with the friction-reduction idea from main.
  • Replace the entire file content with the resolved version below:
# About Our Team

We are a passionate group of engineers dedicated to open-source innovation.
Our mission is to simplify complex development workflows and reduce friction for teams of all sizes.

## Team Members

- Alex - Lead Developer
- Sam - Backend Engineer
- Jordan - Frontend Engineer

What did you just resolve?

The content between <<<<<<< HEAD and ======= was main's version. The content between ======= and >>>>>>> update-bio was the feature branch's version.

You kept the wording from update-bio ("passionate group of engineers") and combined it with main's idea ("reduce friction"). The result is better than either original. In a real team, you would discuss with your teammates which version to keep.

  • Save about.md.
  • Look at the file in Cursor. You should see clean markdown with no <<<<<<<, =======, or >>>>>>> lines anywhere.

Cursor's inline resolution buttons

You may have noticed Cursor showing buttons like "Accept Current Change" or "Accept Incoming Change" above the conflict markers. Those are convenience shortcuts. You are learning the manual approach first because it works in any editor and gives you full control over the final content.

Still seeing conflict markers?

Make sure you deleted all three marker lines, not just the content between them. The file should have no lines starting with <, =, or >.

If the file looks messy, select all the text and paste the resolved version from above. Make sure you saved after editing.

Help me fix my conflict resolution in about.md

✔️ Awesome, I've got everything!

Great. Double check you have saved about.md and the file looks like clean markdown with no marker lines.

ⓧ I'd like to double check the full code

Your about.md should look exactly like this:

# About Our Team

We are a passionate group of engineers dedicated to open-source innovation.
Our mission is to simplify complex development workflows and reduce friction for teams of all sizes.

## Team Members

- Alex - Lead Developer
- Sam - Backend Engineer
- Jordan - Frontend Engineer
Complete the merge

The file is resolved, but Git does not know that yet. You need to stage the file and commit to tell Git the conflict is handled.

  • Stage the resolved file and complete the merge by running these commands:
git add about.md
git commit -m "Merge update-bio: resolve conflict in about.md"

What do these commands do?

Running git add on a conflicted file tells Git you have finished resolving it. Staging the file marks it as resolved.

Running git commit creates the merge commit that joins the two branch histories together into one timeline.

  • Confirm the merge is complete by running:
git status

You should see a clean working tree with nothing to commit. The merge is done.

Seeing 'still merging' or uncommitted changes?

If git status says "All conflicts fixed but you are still merging", you ran git add but forgot the git commit step. Run the commit command above to finish.

If you see an error about unresolved conflicts, open about.md again and confirm no conflict markers remain. Then re-run git add about.md followed by the commit.

Help me complete my merge commit

Push to GitHub and verify the merged history

The merge is complete locally. Before you push, take a look at your local branch history to see how the two branches have rejoined.

What do you think the branch graph looks like now that both branches have been merged into one?

  • Visualize your branch history by running:
git log --oneline --all --graph

You should see a merge commit at the top of main with two parent lines connecting back to where main and update-bio diverged. The branches have rejoined into a single line.

  • Push your merged history to GitHub by running:
git push
  • Switch to your browser where GitHub is open.
  • Navigate to your git-merge-practice repository.
  • Click the commit count (e.g. "5 Commits") or the clock icon to open the commit history.
  • Confirm you can see your merge commit titled "Merge update-bio: resolve conflict in about.md" with both parent branches listed.

Push rejected or merge commit not showing?

If git push is rejected, run git pull --rebase first, then try pushing again. This can happen if something changed on the remote since you last pulled.

If you do not see the merge commit on GitHub, refresh the page. Make sure you are looking at the main branch, not update-bio.

Help me push my merge to GitHub

Secret mission

Resolve a Multi-Section Conflict

You resolved a single conflict region. But real-world merges are messier. Both branches might add entirely new sections to different parts of the same file, creating multiple conflict markers you need to resolve independently. Can you handle it?

Clean Up Your Resources

Clean Up Your Resources

Decide whether to keep your resources running, pause them to come back later, or delete them entirely. This project runs entirely locally (plus a free GitHub repository), so there are no ongoing costs.

Resources you used:

  • GitHub repository git-merge-practice
  • Local project folder git-merge-practice on your Desktop.

Keep everything running

No action needed. Choose this if you are still actively building or want to reference this repository later.

  • Your git-merge-practice repository stays on GitHub for free.
  • Your local git-merge-practice folder stays on your Desktop.

Pause - I'll come back to this later

There is nothing to pause for this project. The GitHub repository and local folder do not consume resources while idle. Come back any time.

Delete - I don't want to use this again

Remove all project resources and start fresh.

  • Delete the local folder by running this in your terminal:
  • macOS/Linux:
  • rm -rf ~/Desktop/git-merge-practice
  • Windows (PowerShell):
  • Remove-Item -Recurse -Force ~\Desktop\git-merge-practice
  • Delete the GitHub repository:
  • Go to your git-merge-practice repository on github.com.
  • Click Settings (the tab in the repository header).
  • Scroll down to the Danger Zone section.
  • Click Delete this repository.
  • Click I want to delete this repository.
  • Click I have read and understand these effects.
  • Type the repository name to confirm, then click Delete this repository.

Nice Work!

Nice Work!

Nice work! You just resolved your first Git merge conflict. That is the exact scenario that trips up most new developers in their first week on a team, and you handled it from the command line.

You've learned how to:

  • Create and switch between feature branches using git switch, simulating a real team workflow where two branches diverge with competing changes.
  • Trigger a merge conflict and read Git's conflict markers (<<<<<<< HEAD, =======, >>>>>>> branch-name) to understand exactly what Git is telling you.
  • Resolve the conflict by choosing content, removing markers, and pushing clean merged history to GitHub with a visualized branch graph.
  • Secret Mission: resolved a multi-section conflict with multiple conflict regions in a single file, combining content from both branches.

Ready to quiz yourself?