Track a Project with Git and GitHub

Introduction

30 Second Summary

Every time you've ever hit "undo" fifty times to get back to a version that worked, you've wished for a better way to track changes. Professional developers solved this problem decades ago with version control.

In this project, you will build a personal recipe book tracked with Git from the very first file. You'll learn to save snapshots of your work, create branches, and publish everything to GitHub with a merged pull request.

What You'll Build

A Git-tracked recipe book with multiple commits, a feature branch, and a public GitHub repository complete with a merged pull request.

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

• A local Git repository with a meaningful commit history showing multiple changes over time.
• A feature branch merged into the main branch, demonstrating the branch-and-merge workflow.
• A public GitHub repository with a pull request in the history that you can share with anyone.
• Secret Mission: Add a .gitignore file and resolve a merge conflict.

Are there any prerequisites?

None. This project includes full setup instructions for Git and GitHub. You don't need any prior coding or command line experience.

Install Git and Set Up Your Identity

Every professional development team tracks their work with version control. It lets you save snapshots of your project at every stage, undo mistakes, and collaborate without overwriting each other's work.

The tool that powers this workflow is Git. In this step, you'll install Git on your Mac, tell it who you are, and create a GitHub account so you can publish your work online later.

In this step, get ready to:

• Install Git and confirm it's working.
• Configure your name and email so Git knows who makes each change.
• Create a free GitHub account for publishing your project.

Check if Git is installed

macOS comes with a shortcut that triggers a Git installation the first time you try to use it. You just need to open Terminal and run a quick command to find out whether Git is already on your machine.

• Press Cmd+Space to open Spotlight.
• Type Terminal and press Enter to open it.
• Check whether Git is installed by running this command:

git --version

This command will either print a version number or trigger an install dialog. Check which scenario matches what you see below.

✔️ I see a version number

If you see something like git version 2.x.x, Git is already installed and ready to go. Any version starting with 2 works for this project.

• Skip ahead to the next substep below.

ⓧ A dialog appeared asking to install developer tools

macOS detected that Git is not installed and is offering to install the Xcode Command Line Tools for you. This package includes Git along with other developer utilities.

• Click Install in the dialog that appeared.
• Wait for the download and installation to finish. This can take a few minutes depending on your internet connection.
• Once it completes, run git --version again in Terminal to confirm the installation worked.

git --version

You should now see a version number starting with 2.

Installation failed?

If you see a message about the software not being available from the Software Update server, try downloading the Command Line Tools manually from the Apple Developer downloads page.

help me install Git on my Mac

Configure your Git identity

Every Git commit records who made the change. Before you start committing, you need to tell Git your name and email so it can attach them to your work.

• Set your name, email, and default branch name by running these commands:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
git config --global init.defaultBranch main

What do these commands do?

• user.name sets the name that appears on every commit you make.
• user.email sets the email attached to your commits. Use the same email you plan to use for GitHub.
• init.defaultBranch main tells Git to name the first branch main when you create a new repository. This matches GitHub's default.

The --global flag applies these settings to every Git project on your machine, so you only need to do this once.

• Confirm your settings saved correctly by running:

git config --list

You should see your name, email, and default branch listed in the output.

Don't see your name or email in the list?

Make sure you included the --global flag when running the config commands. Without it, the settings only apply inside a specific project folder.

help me fix my Git config settings

Create a free GitHub account

GitHub is where you'll publish your Git repository so others can see it. It's free and takes just a minute to set up.

✔️ I already have a GitHub account

• Go to https://github.com and sign in.
• Confirm your email is verified by checking for a green checkmark next to your email in Settings then Emails.

You're all set for the rest of the project.

ⓧ I need to create one

• Go to https://github.com in your browser.
• Click Sign up.
• Enter your email, create a password, and choose a username.
• Complete the verification puzzle and click Create account.
• Check your email inbox for a verification message from GitHub.
• Click the verification link in that email to activate your account.

Is GitHub free?

GitHub's Free plan costs $0 per month and gives you unlimited public and private repositories. That's more than enough for this project and many future ones.

Your machine is ready to go. Git is installed, it knows who you are, and you have a GitHub account waiting. Next up, you'll create your first repository and start tracking changes.

Create Your First Repository and Commit

Git is installed and your identity is configured. Now it is time to put Git to work.

In this step, you will create a project folder, turn it into a Git repository, and practice the core workflow of creating files and recording snapshots called commits. Each commit saves the state of your project at a point in time so you can always look back at what changed.

In this step, get ready to:

• Initialize a new Git repository in a project folder.
• Make your first commit with a README file.
• Add a recipe file and commit it to build a history.

Initialize a Git repository

Every Git project starts with a repository. A repository is a folder where Git tracks all changes to your files.

• Move to your Desktop by running this command:

cd ~/Desktop

• Create your project folder and move into it by running these commands:

mkdir recipe-book
cd recipe-book

• Confirm the folder was created by running:

pwd

You should see a path ending in /Desktop/recipe-book.

• Initialize Git in your project folder by running:

git init

You should see a message saying Initialized empty Git repository followed by the path to your folder.

• Check the state of your new repository by running:

git status

You should see a message about being on branch main with no commits yet.

What is git status?

The git status command shows you the current state of your repository. It tells you which branch you are on, which files have changed, and which changes are ready to be committed.

You will run this command often. It is your go-to tool for understanding what Git sees at any moment.

Seeing 'not a git repository'?

Make sure you ran git init while inside the recipe-book folder. Run pwd to check your location. If you are not inside recipe-book, run cd ~/Desktop/recipe-book to get there.

help me fix a 'not a git repository' error

Create your first file and make your first commit

Git uses a staging area as a middle ground between your files and a commit. You first add changes to the staging area, then record them permanently with a commit. Think of it like placing items on a conveyor belt before they get boxed and shipped.

• Create a README file for your project by running:

echo "# My Recipe Book" > README.md

• Confirm the file was created by running:

ls

You should see README.md in the output.

• Check what Git thinks about this new file by running:

git status

You should see README.md listed under Untracked files in red text. Git sees the file but is not tracking it yet.

• Stage the file by running:

git add README.md

• Check the status again to see what changed:

git status

Now README.md appears under Changes to be committed in green text. The file has moved from your working folder into the staging area.

What just happened?

Running git add moved README.md from the "untracked" zone into the staging area. The staging area is where you prepare exactly which changes you want in your next commit.

This two-step process (add then commit) gives you control over what goes into each snapshot. You can change five files but only commit two of them if you want.

• Record your first commit by running:

git commit -m "Add README with project title"

You should see output confirming the commit, including a short hash (like abc1234) and your commit message.

What is the -m flag?

The -m flag lets you write your commit message inline. Every commit needs a message describing what changed. Without -m, Git opens a text editor for you to type a message instead.

Seeing 'nothing to commit'?

This means you either already committed the file, or forgot to run git add README.md before committing. Run git status to see the current state. If the file is listed under Untracked files, run the git add command again.

help me fix a 'nothing to commit' error in Git

Add a recipe and commit again

Now that you know the workflow, let's add a real recipe file to build up your commit history.

• Create a file called pancakes.md with a full recipe by running this command:

cat > pancakes.md << 'EOF'
# Pancakes

## Ingredients

- 1 cup flour
- 2 eggs
- 1 cup milk
- 2 tbsp sugar
- 1 tsp baking powder
- Pinch of salt
- Butter for cooking

## Steps

1. Mix flour, sugar, baking powder, and salt in a bowl.
2. Whisk eggs and milk together, then add to dry ingredients.
3. Stir until just combined (lumps are okay).
4. Heat a pan over medium heat and add butter.
5. Pour 1/4 cup batter per pancake.
6. Flip when bubbles form on top, cook until golden.
EOF

What does this command do?

The cat > pancakes.md << 'EOF' syntax creates a file and writes everything between the first EOF and the last EOF into it. This is called a "heredoc" and is a quick way to create multi-line files directly in the terminal.

• Confirm the file was created by running:

ls

You should see both README.md and pancakes.md in the output.

• Stage the new recipe file by running:

git add pancakes.md

• Commit the recipe by running:

git commit -m "Add pancake recipe"

You should see output confirming a new commit was created.

• View your full commit history by running:

git log --oneline

You should see two lines, one for each commit. The most recent commit appears at the top.

What does --oneline do?

The --oneline flag shows each commit on a single line with just the short hash and message. Without it, git log shows the full details (author, date, full hash) for each commit, which takes up more space.

✔️ Awesome, I've got everything!

Great. Make sure both files are saved and your git log --oneline shows two commits.

ⓧ I'd like to double check the full code

Here is what each file should contain at this point.

README.md:

# My Recipe Book

pancakes.md:

# Pancakes

## Ingredients

- 1 cup flour
- 2 eggs
- 1 cup milk
- 2 tbsp sugar
- 1 tsp baking powder
- Pinch of salt
- Butter for cooking

## Steps

1. Mix flour, sugar, baking powder, and salt in a bowl.
2. Whisk eggs and milk together, then add to dry ingredients.
3. Stir until just combined (lumps are okay).
4. Heat a pan over medium heat and add butter.
5. Pour 1/4 cup batter per pancake.
6. Flip when bubbles form on top, cook until golden.

You can view the contents of any file in your terminal by running cat README.md or cat pancakes.md.

Seeing only one commit?

Run git status to check if pancakes.md is still untracked or staged. If it is listed under Untracked files, you need to run git add pancakes.md followed by git commit -m "Add pancake recipe".

help me figure out why my second commit is missing

You now have a repository with two commits tracking real changes. Next up, you will create a branch to work on a new recipe without touching your existing work.

Create a Branch and Make Changes

You now have a repository with two commits tracking your recipe book's history. The next goal is to add a new recipe without touching your stable main branch.

In professional development, you never work directly on the main branch. Instead, you create a separate branch to develop a feature in isolation, then merge it back when it's ready. This keeps the main branch clean while you experiment freely.

In this step, get ready to:

• Create a feature branch and switch to it.
• Add a smoothie recipe and commit it on the feature branch.
• Switch between branches to see how Git isolates changes.

Create and switch to a new branch

A branch is like a parallel timeline for your project. Changes you make on one branch stay invisible to other branches until you merge them together.

• Create a new branch called add-smoothie-recipe and switch to it by running this command:

git switch -c add-smoothie-recipe

What does this command do?

The git switch -c command does two things at once: it creates a new branch (-c stands for "create") and immediately switches you onto it.

Your new branch starts as an exact copy of wherever you were (main in this case). From here, any new commits go on the feature branch only.

• Confirm you're on the new branch by running:

git status

You should see On branch add-smoothie-recipe at the top of the output.

• View all branches in your repository by running:

git branch

You should see two branches listed: main and add-smoothie-recipe. The asterisk (*) marks your current branch.

Seeing an error about unknown switch?

If your terminal says git switch is not recognized, your Git version may be older than 2.23. Run git --version to check. Update Git using the Xcode Command Line Tools or download the latest version from git-scm.com.

help me fix a git switch error

Make commits on your feature branch

Now that you're on your feature branch, every commit you make stays here. The main branch won't see these changes until you merge later.

• Create a new file called smoothie.md with a berry smoothie recipe by running this command:

cat > smoothie.md << 'EOF'
# Berry Smoothie

## Ingredients

- 1 cup mixed berries (fresh or frozen)
- 1 banana
- 1 cup yogurt
- 1/2 cup milk
- 1 tbsp honey

## Steps

1. Add all ingredients to a blender.
2. Blend on high for 30-60 seconds until smooth.
3. Pour into a glass and serve immediately.
EOF

What does this command do?

The cat > smoothie.md << 'EOF' syntax is called a heredoc. It writes everything between the two EOF markers into the file smoothie.md.

This lets you create a multi-line file directly from the terminal without opening a text editor.

• Confirm the file was created by running:

ls

You should see smoothie.md listed alongside README.md and pancakes.md.

• Stage and commit your new smoothie recipe by running these commands:

git add smoothie.md
git commit -m "Add berry smoothie recipe"

What's happening here?

The git add command moves your file into the staging area. This is Git's way of letting you choose exactly which changes go into the next commit.

The git commit -m command saves those staged changes permanently with a descriptive message.

You should see a confirmation message mentioning the file was created.

✔️ Awesome, I've got everything!

Great. Make sure you see the commit confirmation before moving on.

ⓧ I'd like to double check the full code

Here is what smoothie.md should contain:

# Berry Smoothie

## Ingredients

- 1 cup mixed berries (fresh or frozen)
- 1 banana
- 1 cup yogurt
- 1/2 cup milk
- 1 tbsp honey

## Steps

1. Add all ingredients to a blender.
2. Blend on high for 30-60 seconds until smooth.
3. Pour into a glass and serve immediately.

• Now update README.md to list both recipes by running this command:

cat > README.md << 'EOF'
# My Recipe Book

A collection of my favorite recipes.

## Recipes

- [Pancakes](pancakes.md)
- [Berry Smoothie](smoothie.md)
EOF

What does this update do?

You're replacing the single-line README with a proper project description and a linked list of recipes. The [text](file) syntax is a Markdown link that will be clickable on GitHub.

• Verify the update by running:

cat README.md

You should see the recipe list with links to both files.

• Stage and commit the updated README by running these commands:

git add README.md
git commit -m "Update README with recipe list"

• View your full commit history on this branch by running:

git log --oneline

You should see four commits listed. The two original commits from main plus your two new feature branch commits.

✔️ Awesome, I've got everything!

Great. Your feature branch now has both new changes committed.

ⓧ I'd like to double check the full code

Here is what README.md should contain on your feature branch:

# My Recipe Book

A collection of my favorite recipes.

## Recipes

- [Pancakes](pancakes.md)
- [Berry Smoothie](smoothie.md)

Seeing 'nothing to commit'?

This means your file wasn't saved before you ran git add. Run cat README.md to check the file content. If it still shows only # My Recipe Book, re-run the cat > README.md << 'EOF' command from above, then stage and commit again.

help me fix my git commit

Switch back to main and observe the difference

Here's where branches get interesting. Switching branches changes the files on your computer instantly.

• Switch back to the main branch by running:

git switch main

• List your files by running:

ls

Notice that smoothie.md is gone. It only exists on the add-smoothie-recipe branch.

• View the commit history on main by running:

git log --oneline

You should see only two commits here. The smoothie commits exist only on the feature branch.

Where did the file go?

Git didn't delete your smoothie recipe. Each branch maintains its own version of the project. When you switch branches, Git swaps the files in your folder to match that branch's state.

This is the power of branches. You can work on new features in isolation without risking stable code on main.

• Switch back to your feature branch by running:

git switch add-smoothie-recipe

• Run ls again to confirm smoothie.md is back.

Your feature branch is ready with two solid commits. Next up, you'll push this branch to GitHub and open your first pull request.

Push to GitHub and Open a Pull Request

Your recipe book has a solid history. You have commits on main and a feature branch with new recipes waiting to be reviewed.

Right now, everything lives only on your computer. In this step, you'll push your repository to GitHub and open a pull request to propose merging your smoothie recipe into the main branch.

In this step, get ready to:

• Create a remote repository on GitHub.
• Push both branches to GitHub.
• Open a pull request for your feature branch.

Create a remote repository on GitHub

A remote repository is a copy of your project hosted on a server that other people can access. You need one on GitHub before you can push your local commits.

• Switch to your browser where you're signed into GitHub.
• Click the + icon in the top-right corner of any GitHub page.
• Select New repository.
• Enter recipe-book as the repository name.
• Leave it set to Public.
• Do NOT check any of the initialization options (no README, no .gitignore, no license).
• Click Create repository.

Why skip the initialization options?

You already have a local repository with commits. If GitHub creates its own README or .gitignore, the remote will have a different history than your local repo. That causes conflicts on your very first push.

• On the next page, GitHub shows setup instructions. Find the HTTPS URL near the top (it looks like https://github.com/your-username/recipe-book.git). Copy it.

Keep this tab open

You'll need this URL in a moment when you connect your local repo to GitHub.

Push your main branch to GitHub

Pushing uploads your local commits to the remote repository. You'll start with the main branch so GitHub has your project's foundation.

• Switch back to main by running this command:

git switch main

• Connect your local repository to the GitHub remote by running this command:

git remote add origin [[REPO_URL="https://github.com/your-username/recipe-book.git"]]

What does this command do?

This registers a remote called origin that points to your GitHub repository. The name origin is a convention for your primary remote.

• Push your main branch to GitHub by running this command:

git push -u origin main

What does -u do?

The -u flag sets up tracking between your local main and the remote origin/main. After this, future pushes and pulls will know which remote branch to target automatically.

GitHub will ask you to authenticate

When you push for the first time, GitHub needs to verify your identity. A browser window may open asking you to sign in to GitHub. Follow the prompts to authorize access.

If the browser flow doesn't appear, GitHub may ask for a username and password in the terminal. For the password, you'll need a Personal Access Token (not your GitHub password). You can create one at github.com/settings/tokens.

• Refresh your GitHub repository page in the browser. You should see your README.md and pancakes.md files listed.

Push rejected or authentication failed?

Make sure you copied the HTTPS URL correctly from GitHub. Run git remote -v to check what URL your origin points to.

If authentication fails, double-check that you signed in with the same GitHub account that owns the repository.

Help me fix a git push authentication error

Push your feature branch and open a pull request

Now you'll push the feature branch and create a pull request. A pull request is how you propose merging one branch into another on GitHub. It gives teammates a chance to review your changes before they land in the main branch.

• Switch to your feature branch by running this command:

git switch add-smoothie-recipe

• Push the feature branch to GitHub by running this command:

git push -u origin add-smoothie-recipe

• You should see output confirming a new remote branch was created.
• Switch to your browser and go to your recipe-book repository on GitHub.
• You'll see a yellow banner near the top that says your branch had recent pushes. Click Compare & pull request.

What is a pull request?

A pull request is a proposal to merge changes from one branch into another. On a team, pull requests give others a chance to review your code, leave comments, and approve before the merge happens.

Even working solo, pull requests create a clean record of what changed and why.

• On the pull request form, enter a title like Add berry smoothie recipe.
• In the description field, write a brief summary of what this branch adds (for example, "Adds a new smoothie recipe and updates the README with a recipe list").
• Click Create pull request.

You should now see your pull request page with the title you entered, showing the commits from your feature branch.

Don't see the Compare & pull request banner?

The banner only appears briefly after a push. If you missed it, click the Pull requests tab at the top of your repository, then click New pull request. Select main as the base branch and add-smoothie-recipe as the compare branch.

Help me create a pull request on GitHub

Your recipe book is now live on GitHub with a pull request open for review. Next up, you'll merge that pull request and sync the changes back to your local machine.

Merge Your Pull Request

Your recipe book is on GitHub with a pull request waiting to be merged. Now comes the payoff: integrating your feature branch's work into main.

After merging on GitHub, your local machine won't know about the change automatically. You'll pull the merged code down and clean up the feature branch to complete the professional workflow.

In this step, get ready to:

• Merge your pull request on GitHub.
• Pull the merged changes to your local machine.
• Clean up the feature branch.

Review and merge on GitHub

A pull request isn't just a request to merge code. It's a chance to review what changed before it becomes part of the main project.

• Return to your pull request page on GitHub in your browser.
• Click the Files changed tab to see what your feature branch added.

What is the Files changed tab?

This tab shows a diff of every file your branch modified. Green lines are additions and red lines are deletions.

In a team setting, this is where code review happens. Teammates read the diff, leave comments, and approve or request changes before merging.

You've reviewed your changes. Time to merge them into main.

• Click the Conversation tab to return to the main pull request view.
• Scroll down and click Merge pull request.
• Click Confirm merge.

GitHub now shows a purple merged badge on your pull request. Your smoothie recipe commits are now part of main on GitHub.

• Click Delete branch to clean up the remote feature branch.

Why delete the branch?

Once a feature branch is merged, it has served its purpose. Deleting it keeps your repository tidy and signals to collaborators that the work is complete.

This only deletes the branch on GitHub. Your local copy still has it until you remove it manually.

Pull the merged changes locally

GitHub knows about the merge, but your local repository is still sitting on the feature branch with no idea anything changed on the remote. You need to switch to main and pull the updates down.

• Switch back to your terminal.
• Switch to the main branch by running this command:

git switch main

• Pull the merged changes from GitHub by running:

git pull origin main

What does git pull do?

The git pull command fetches new commits from the remote repository and merges them into your current branch. It combines two operations: git fetch (download) and git merge (integrate).

• Verify the smoothie recipe is now on main by running:

ls

You should see smoothie.md listed alongside README.md and pancakes.md.

• View the full commit history by running:

git log --oneline

You should see all your commits listed, including the ones from the feature branch and the merge commit from GitHub.

Don't see smoothie.md?

Make sure you switched to main before pulling. Run git status to confirm you're on the main branch.

If git pull failed with an authentication error, your credentials may have expired. Try the pull command again and re-authenticate when prompted.

Help me debug why git pull isn't bringing my smoothie.md file to main.

Clean up your local feature branch

The feature branch did its job. Keeping it around after merging adds clutter, so the final housekeeping step is to delete it locally.

• Delete the merged feature branch by running:

git branch -d add-smoothie-recipe

What does the -d flag do?

The -d flag stands for delete, but it's a safe delete. Git refuses to delete a branch that hasn't been fully merged, protecting you from accidental data loss.

• Confirm only main remains by running:

git branch

You should see only * main in the output. The asterisk means it's your current branch.

Branch not deleted?

If you see an error saying the branch is not fully merged, make sure you ran git pull origin main first. Git needs to know the merge happened before it allows a safe delete.

Help me understand why Git won't let me delete my feature branch.

Secret mission

Add a .gitignore and Resolve a Merge Conflict

In the real world, merge conflicts happen when two people edit the same line of the same file. Most beginners panic when they see conflict markers for the first time. In this mission, you'll intentionally cause a merge conflict and calmly resolve it, turning one of Git's scariest moments into a routine skill.

Clean Up Your Resources

Clean Up Your Resources

This project runs entirely locally and on GitHub's free plan, so there are no ongoing costs. Decide whether to keep your resources running, come back later, or delete them entirely.

Resources you used:

• Local recipe-book folder on your Desktop.
• GitHub recipe-book repository (public).

Keep everything running

No action needed. Choose this if you plan to keep building your recipe book or want the repository visible on your GitHub profile.

• Your local files and GitHub repository stay exactly as they are.
• There are no running processes or recurring costs to worry about.
• Git remains installed on your machine for future projects.

Pause - I'll come back to this later

There are no running processes or costs to pause. Your local files and GitHub repository remain available whenever you return.

• If you want to hide the repository from your public profile temporarily, go to your repository on GitHub, click Settings, scroll to the Danger Zone section, and change the visibility to private.
• You can make it public again at any time from the same settings page.

Delete - I don't want to use this again

Remove all project files and the GitHub repository to start fresh.

• Delete the local project folder.

macOS

• Run this command in Terminal:

rm -rf ~/Desktop/recipe-book

Windows

• Run this command in Command Prompt:

rmdir /s /q %USERPROFILE%\Desktop\recipe-book

• Delete the GitHub repository:
• Go to your recipe-book repository on GitHub.
• Click Settings (in the repository navigation bar).
• Scroll down to the Danger Zone section.
• Click Delete this repository and follow the confirmation prompts.

What about Git itself?

Git stays installed on your machine. It was added through Xcode Command Line Tools and is useful for any future coding project. There is no need to remove it.

Nice Work!

Nice Work!

You just learned the professional Git workflow that powers virtually all software development. You now have a public GitHub repository with a real commit history, a merged pull request, and the confidence to track any project with version control.

You've learned how to:

• Initialize a Git repository and build a meaningful commit history that tracks file changes over time.
• Create a feature branch, push it to GitHub, and open a pull request for review.
• Merge a pull request on GitHub and sync the changes back to your local machine.
• Created a .gitignore file, intentionally triggered a merge conflict, and resolved it by hand.

Ready to quiz yourself?