Creating Your First Repository

Creating Your First Repository

Creating Your First Repository

Introduction

Now that Git is installed and configured on your system, it's time to create your first repository. This lesson will walk you through initializing a Git repository, understanding what happens behind the scenes, and exploring the mysterious .git folder that makes all the magic happen.

What Happens When You Initialize a Repository?

When you initialize a Git repository, you're telling Git to start tracking changes in a specific folder. Git transforms an ordinary directory into a version-controlled project by creating a hidden .git folder that contains all the version control machinery.

Think of it like installing a security camera system in your house. The folder is your house, and the .git directory is the recording equipment that watches and remembers everything that happens.

Creating a New Repository

There are two main scenarios for creating a repository: starting a brand new project or adding version control to an existing project. We'll cover both.

Starting a Fresh Project

Let's create a new project from scratch. Open your terminal and follow these steps:

Step 1: Create a Project Directory

First, create a new folder for your project and navigate into it:

mkdir my-first-repo
cd my-first-repo

You can name your project anything you want. Use lowercase letters and hyphens for multi-word names (like personal-website or todo-app).

Step 2: Initialize Git

Now comes the magic command:

git init

You should see a message like:

Initialized empty Git repository in /path/to/my-first-repo/.git/

Congratulations! You've just created your first Git repository. The folder now contains a hidden .git directory that stores all version control information.

Step 3: Verify Initialization

To confirm Git is tracking your folder, check the repository status:

git status

You should see output indicating you're on a branch (likely called "main" or "master") and that there are no commits yet.

Adding Git to an Existing Project

If you already have a project folder with files in it, the process is similar:

Navigate to Your Project:

cd /path/to/existing-project

Initialize Git:

git init

Git will initialize the repository without touching your existing files. They'll be listed as "untracked files" when you run git status, ready for you to start version controlling them.

Understanding the .git Folder

The .git folder is the heart of your repository. It's hidden by default because you shouldn't manually edit its contents in most cases. Let's explore what's inside.

Viewing Hidden Files

To see the .git folder:

On macOS/Linux:

ls -la

On Windows (Command Prompt):

dir /a

On Windows (PowerShell):

Get-ChildItem -Force

You should see .git listed among your files.

The .git Folder Structure

Navigate into the .git folder to explore its contents:

cd .git
ls

Here's what you'll find and what each component does:

HEAD

This file points to the current branch you're working on. It's a reference that tells Git which branch is currently checked out. Open it with a text editor and you'll see something like:

ref: refs/heads/main

This means you're currently on the "main" branch.

config

This file contains repository-specific configuration settings. These are the "local" settings that override global configuration. You can view it with:

cat config

It might contain settings like your remote repository URLs, branch tracking information, and other project-specific preferences.

description

This file is used by GitWeb (a web interface for Git). For most users, it's not important and can be ignored. It contains a default message unless you're using GitWeb.

hooks/

This directory contains scripts that Git can execute automatically at certain points in the Git workflow. For example, you could have a hook that runs tests before allowing a commit, or one that formats code automatically.

Hook files have names like pre-commit, post-merge, or pre-push. They're powerful for automating workflow tasks but aren't necessary for basic Git usage.

objects/

This is where Git stores all the content of your repository. Every file you commit, every version you save, every commit message—everything goes here. Git uses a clever compression system that makes this storage very efficient.

Objects are organized by their SHA-1 hash values. You'll see subdirectories with two-character names (like a3, f2, 8b) that contain the actual object files. Don't worry about the cryptic structure—Git handles all of this automatically.

refs/

This directory contains pointers to commits. It's organized into subdirectories:

  • refs/heads/ contains references to local branches
  • refs/tags/ contains references to tags (markers for specific commits)
  • refs/remotes/ contains references to remote branches

Each file in these directories contains a commit hash that represents the tip (latest commit) of that branch or tag.

info/

This directory contains additional repository information. The most notable file here is exclude, which works like a local .gitignore file but isn't shared with other users.

logs/

Git keeps logs of changes to references (branches and HEAD). This is what powers commands like git reflog, which lets you see a history of where HEAD has pointed over time.

Why the .git Folder Matters

Understanding the .git folder helps you grasp what Git is actually doing:

Complete History

Everything Git knows about your project is in this folder. If you delete it, you lose all version history (though your current files remain). If you copy it, you copy the entire project history.

Portable

Because all version control information is in one folder, your repository is completely self-contained. You can move it, back it up, or share it easily.

The Working Directory vs. The Repository

Your project folder has two parts:

  • The working directory: Your actual project files that you edit
  • The repository (the .git folder): The version control database

When you "commit" changes, Git takes a snapshot of the working directory and stores it in the repository.

Important Safety Notes

Don't Edit .git Manually

The .git folder is a carefully structured database. Manually editing files inside it can corrupt your repository. Always use Git commands to interact with your repository.

Don't Commit the .git Folder

When you push your repository to GitHub or another hosting service, you push the .git folder—that's how the remote server gets your full history. However, if you have a Git repository inside another Git repository, don't commit the nested .git folder. This creates confusion. We'll cover submodules (the proper way to handle nested repositories) in a later lesson.

Backup Matters

Your project history only exists in .git. If this folder gets corrupted or deleted, you lose everything. This is why pushing to remote repositories (like GitHub) is important—it creates a backup of your entire history.

Checking Repository Status

After initializing a repository, frequently check its status:

git status

This command shows:

  • Which branch you're on
  • Which files are modified
  • Which files are staged for commit
  • Which files are untracked

It's the command you'll use most often, serving as your dashboard for understanding your repository's current state.

Creating Your First File

Let's put some content in your repository:

Create a File:

echo "# My First Repository" > README.md

This creates a file called README.md with a heading.

Check Status:

git status

Git will show README.md as an "untracked file"—it exists in your working directory but Git isn't watching it yet.

Stage the File:

git add README.md

Now the file is "staged," meaning it's marked for inclusion in the next commit.

Check Status Again:

git status

You'll see README.md listed under "Changes to be committed."

Make Your First Commit:

git commit -m "Initial commit with README"

Congratulations! You've made your first commit. Git has saved a snapshot of your project.

Exploring Your Commit

View your commit history:

git log

You'll see your commit with:

  • A unique commit hash (like a3f2e9b4c5d6...)
  • Your name and email
  • The timestamp
  • Your commit message

This is the beginning of your project's history.

Re-initializing and Removing Git

What If You Run git init Twice?

Running git init in a folder that already has a .git folder is safe. Git will simply report that it reinitialized the existing repository. It won't delete your history or commits.

Removing Git from a Project

If you want to stop tracking a project with Git, simply delete the .git folder:

macOS/Linux:

rm -rf .git

Windows:

rmdir /s .git

Your files will remain, but all version history will be gone. The folder becomes a regular directory again.

Best Practices for New Repositories

Create a README First

Always create a README.md file as your first commit. This file should explain what your project is, how to use it, and any important information. It's the front door to your project.

Add a .gitignore File

Create a .gitignore file to tell Git which files to never track. This typically includes:

  • Build artifacts
  • Dependencies (like node_modules/)
  • Environment variables
  • Operating system files (like .DS_Store)
  • IDE-specific files

Example .gitignore:

node_modules/
.env
*.log
.DS_Store

Make a Meaningful First Commit

Your first commit message should be clear. "Initial commit" or "Initial project setup" are standard and appropriate.

Common Questions

Can I Have Multiple Git Repositories on My Computer?

Absolutely! Each project should be its own repository. Git repositories are independent of each other.

Can I Have Nested Git Repositories?

Generally, you shouldn't nest repositories unless you're using Git submodules or subtrees (advanced topics). If you accidentally initialize Git in a parent folder that contains Git repositories, you may encounter confusion.

Is My Repository Private?

A local repository is completely private—it exists only on your computer. It only becomes public when you push it to a hosting service like GitHub and explicitly make it public.

How Much Space Does .git Take?

Initially, very little. As your project grows, .git stores compressed versions of your files efficiently. Even large projects rarely have .git folders larger than a few hundred megabytes.

Next Steps

You've successfully created your first Git repository and understand the structure that makes version control possible. The .git folder is now working behind the scenes, ready to track every change you make.

In the next lesson, you'll learn about the fundamental Git workflow: staging changes, making commits, and building a meaningful project history. The repository you've created here will be the foundation for practicing these essential skills.

Remember: every Git repository starts exactly like this—with a simple git init command. You've now got the same powerful version control system that manages projects as large as the Linux kernel or as small as a personal todo list. The tool is the same; it scales to your needs.