Learning Git from the start with an example project

Learning Git through an example

The objective of this article is to help you learning Git through an example project. In short, this article contains a step-by-step, example project that shows how to create a Git repository from scratch, make the first commit, navigate around the repo, and perform fundamental operations like staging, committing, branching, and merging. All commands are annotated with explanations. You can copy, paste, and adapt this guide as a helper during your Git adventures!.

In this tutorial you’ll learn:

1. Initialized a local Git repository (git init).
2. Created and staged files (git add).
3. Committed changes (git commit).
4. Explored history (git log) and differences (git diff).
5. Branched off the main branch and merged changes back in.
6. Tagged a version.
7. (Optional) Pushed your local repository to a remote service.

By the end of it, you should have a solid grasp of the Git workflow: Make changes → Stage → Commit → (Optionally) Branch → Merge → Push.

For a more traditional tutorial see: Git tutorial: Version control from the ground up.

1. Create a New Folder & Initialize a Git Repository

# 1. Create a new folder for your sample project
mkdir my-sample-project

# 2. Navigate into the folder
cd my-sample-project

# 3. Initialize a Git repository
git init

Explanations:

• mkdir my-sample-project: Makes a new folder named my-sample-project.
• cd my-sample-project: Enters that folder so that subsequent commands operate there.
• git init: Transforms the current folder into a Git repository by creating a hidden .git directory.

2. Create Your First File & First Commit

# 1. Create a simple text file (you can use echo, a code editor, or any other method)
echo "Hello, Git!" > hello.txt

# 2. Check the status of your repo (you'll see hello.txt as 'untracked')
git status

# 3. Stage the new file for a commit
git add hello.txt

# 4. Commit your staged changes with a short message
git commit -m "Add hello.txt with a greeting"

Explanations:

• echo “Hello, Git!” > hello.txt: Creates a file named hello.txt containing the text “Hello, Git!”.
• git status: Shows which files are new, modified, or staged.
• git add hello.txt: Tells Git to include hello.txt in the next commit.
• git commit -m “Add hello.txt with a greeting”: Captures a snapshot of the staged file(s) in the repository’s history, with a message describing what was done.

3. Explore the Repository

# 1. View the commit history (so far, you only have one commit)
git log

# 2. See a one-line-per-commit summary (useful for quick reference)
git log --oneline

# 3. Check the status to confirm there are no uncommitted changes

Explanations:

• git log: Lists the full commit history, including commit hashes and messages.
• git log –oneline: Displays a condensed version, typically showing the first 7 characters of the commit hash and the commit message.
• git status: Reassures you that everything is up to date or shows any new changes since the last commit.

4. Make Changes & Stage/Commit Again

# 1. Append a line to hello.txt
echo "This is our sample project to learn Git." >> hello.txt

# 2. See what's changed
git diff

# 3. Stage your changes
git add hello.txt

# 4. Commit the changes
git commit -m "Update hello.txt with a second line"

Explanations:

• echo “Some text” >> hello.txt: Appends another line to hello.txt (using >>).
• git diff: Shows how the working file differs from the last commit.
• git add hello.txt: Moves the updated file to the staging area.
• git commit -m …: Records the new snapshot in Git history.

5. Create & Switch to a New Branch

# 1. Create a new branch for experimenting
git branch feature-experiment

# 2. Switch to that new branch
git switch feature-experiment
# or, for older Git:
# git checkout feature-experiment

# 3. Confirm which branch you're on
git branch

Explanations:

• git branch feature-experiment: Makes a new branch named feature-experiment.
• git switch feature-experiment: Moves you to that branch so you can work there without affecting the original branch.
• git branch: Lists all local branches; the asterisk (*) indicates the active branch.

6. Modify Files in the New Branch

# 1. Modify hello.txt again
echo "This line only exists in the 'feature-experiment' branch." >> hello.txt

# 2. Check status and diff
git status
git diff

# 3. Stage and commit changes
git add hello.txt
git commit -m "Add branch-specific line to hello.txt"

Explanations:

• You’re now working in the feature-experiment branch, so any commits you make here won’t appear in master or main until you merge.
• git diff helps you review the exact changes before committing.

7. Merge the New Branch Back Into Master/Main

1. Switch back to the master (or main) branch:

git switch master

2. Merge the changes from feature-experiment into master:

git merge feature-experiment

3. Resolve conflicts if any appear. (They won’t in this simple example.)
4. Check that everything is merged:

git log --oneline --graph --decorate
git status

5. Optionally, delete the merged branch:

git branch -d feature-experiment

Explanations:

• git switch master: Changes the working branch back to master.
• git merge feature-experiment: Pulls all commits from feature-experiment into master.
• git branch -d feature-experiment: Safely deletes the branch now that it’s merged.

8. Tag a Version (Optional)

# 1. Create a lightweight tag
git tag v0.1

# 2. Or create an annotated tag with a message
git tag -a v0.1 -m "First demo version"

# 3. List all tags
git tag

Explanations:

• git tag v0.1: Assigns a lightweight tag to the current commit.
• git tag -a v0.1 -m “First demo version”: Creates an annotated tag (which can hold a message and author info)..

9. Optional: Push to a Remote

# 1. Link your local repo to a remote (e.g., GitHub)
git remote add origin https://github.com/YourUsername/my-sample-project.git

#  2. Push your commits to the remote
git push -u origin master

# 3. Push other branches if desired
git push -u origin feature-experiment

Final Directory Structure

After these steps, your my-sample-project folder might look like this:

my-sample-project/
├── .git/             (Hidden folder containing Git metadata)
├── hello.txt       (Our sample file)

What’s next

If you’re brand new to Git, you now have a solid foundation to keep learning and experimenting!, and you can do just that by either going to:

• Our basic and general Git tutorial: Git tutorial: Version control from the ground up.
• Out more advanced list of Git commands: Advanced Git topics and commands.

Happy coding!