This guide shows you how to create your first Git repository or fetch an
existing project. You will use git init to start a new project and
git clone to fetch a remote project. By the end, you will understand what
the .git/ folder contains and why it is essential.
Prerequisites: Git installed and configured (identity, editor).
What you will learn
- Create an empty repository with
git init, in a new or an already existing folder - Fetch a remote project with its whole history, using
git clone - Read the content of the
.git/folder, where Git keeps what it stores for your project - Choose between a normal repository and a bare repository
Create a local repository with git init
The git init command turns an ordinary folder into a Git repository. It
creates a .git/ subfolder that holds all the versioning machinery.
Initialize a new project
-
Create the folder and initialize it:
Terminal window git init my-portfolioExpected output:
Initialized empty Git repository in /home/bob/Projets/my-portfolio/.git/ -
Enter the project:
Terminal window cd my-portfolio -
Check that Git is active:
Terminal window git statusExpected output:
On branch mainNo commits yetnothing to commit (create/copy files and use "git add" to track)
Git writes its messages in the system language. The outputs in this guide
are in English (LANG=C.UTF-8). With LANG=fr_FR.UTF-8, Git 2.47.3
translates git init and git status ("Dépôt Git vide initialisé", "Sur la
branche main"), but not git diff or git log. On a system set to French,
you will therefore read different words for the same meaning.
If the folder already exists, you can initialize Git inside it:
cd my-existing-projectgit initGit does not modify any of your files. It simply creates the .git/ folder
next to your existing files.
Create a .gitignore from the start
Before your first commit, always create a .gitignore file to exclude the
files that do not belong in the Git history:
cat > .gitignore << 'EOF'# Dependenciesnode_modules/vendor/.venv/
# Build filesdist/build/*.o
# Editors and IDEs.vscode/.idea/*.swp
# Secrets (NEVER commit).env*.key*.pemEOFClone a remote repository with git clone
The git clone command downloads a remote project with its whole
history. It is like photocopying a complete binder instead of creating it
from scratch.
Clone over SSH (recommended)
git clone git@github.com:username/my-project.gitReplace username/my-project with a repository your account can access.
This form uses the SSH key set up in the
installation guide:
no password to enter.
Clone over HTTPS
The public repository octocat/Hello-World, a GitHub demo repository, can
be cloned without an account. You can therefore try it right away:
git clone https://github.com/octocat/Hello-World.gitHere is the output observed with Git 2.47.3. The numbers change from one
repository to another, so they are replaced here by ...:
Cloning into 'Hello-World'...remote: Enumerating objects: ..., done.remote: Total ... (delta ...), reused ... (delta ...), pack-reused ... (from ...)Receiving objects: 100% (.../...), done.Git creates the Hello-World folder and downloads the whole history of the
project into it. The lines that start with remote: come from the server,
which is preparing the transfer. The Receiving objects line tells you that
your machine is receiving the data. This progress line only appears in a
terminal, not in a script or a continuous integration log.
On a repository with a longer history, you will also see a
Resolving deltas: 100% (.../...), done. line. A delta is the difference
between two versions of the same file, which the server sends instead of the
complete file. Hello-World is tiny: the server sends no delta, so that
line does not appear.
Then enter the folder with cd Hello-World and run git log --oneline. The
commits of the project are displayed without a new connection to the server,
because the whole history is already on your machine.
Useful options of git clone
| Option | Use | Example |
|---|---|---|
<folder> | Rename the local folder | git clone url my-folder |
--depth 1 | Shallow clone (latest commit only) | Useful for very large repositories |
--branch <name> | Clone a specific branch | git clone --branch develop url |
--recurse-submodules | Include submodules | Projects with Git dependencies |
Example of a clone into a custom folder:
git clone https://github.com/octocat/Hello-World.git my-folderGit creates my-folder instead of Hello-World. The output is the same,
with Cloning into 'my-folder'... as the first line.
Understand the structure of the .git/ folder
After a git init, explore the content of the .git/ folder (a
git clone adds other files to it, such as index and packed-refs):
ls -la .git/Expected output:
total 40drwxrwxr-x 7 bob bob 4096 Nov 15 18:46 .drwxrwxr-x 3 bob bob 4096 Nov 15 18:46 ..-rw-rw-r-- 1 bob bob 21 Nov 15 18:46 HEADdrwxrwxr-x 2 bob bob 4096 Nov 15 18:46 branches-rw-rw-r-- 1 bob bob 92 Nov 15 18:46 config-rw-rw-r-- 1 bob bob 73 Nov 15 18:46 descriptiondrwxrwxr-x 2 bob bob 4096 Nov 15 18:46 hooksdrwxrwxr-x 2 bob bob 4096 Nov 15 18:46 infodrwxrwxr-x 4 bob bob 4096 Nov 15 18:46 objectsdrwxrwxr-x 4 bob bob 4096 Nov 15 18:46 refsEach item has a precise role:
| File / Folder | Role |
|---|---|
HEAD | Points to the current branch (e.g. ref: refs/heads/main) |
config | Local configuration of the repository (--local level) |
objects/ | Stores all Git objects (commits, trees, files) |
refs/ | Holds the pointers to branches and tags |
hooks/ | Scripts run automatically on certain events |
info/ | Information files (e.g. local exclusions) |
In the list shown above, you can ignore description (used only by the
GitWeb web interface) and branches/ (an old mechanism that Git no longer
uses).
Normal repository vs bare repository
Git distinguishes two types of repositories:
| Characteristic | Normal repository | Bare repository |
|---|---|---|
| Working copy | Yes (your files) | No |
.git/ folder | Subfolder of the project | The whole project |
| Use | Daily development | Server (hosting) |
| Created with | git init | git init --bare |
A bare repository only contains the Git database, without a working
copy. A Git server that receives push operations needs one, like the one in
the lesson host a Git server
(in French). You never work directly in a bare repository.
git init --bare my-server.gitls my-server.gitThe command creates the my-server.git folder and puts the contents of
.git/ directly in it, with no working directory:
Initialized empty Git repository in /home/bob/Projets/my-server.git/HEADbranchesconfigdescriptionhooksinfoobjectsrefsFor a personal project, you will not need to create a bare repository: a hosting platform such as GitHub or GitLab handles the server side for you.
Troubleshooting: common problems
| Symptom | Likely cause | Solution |
|---|---|---|
fatal: not a git repository | You are not in a folder containing .git/ | Move to the right folder with cd or initialize with git init |
Permission denied (publickey) on an SSH clone | SSH key not set up | Follow the SSH section of the installation guide |
| HTTPS clone asks for a password | Personal token required | GitHub no longer accepts the account password for Git, and GitLab requires a Personal Access Token as soon as two-factor authentication is active |
git init creates a master branch | init.defaultBranch not set | git config --global init.defaultBranch main |
fatal: destination path ... already exists | The target folder already exists and is not empty | Clone into another folder (last argument of git clone) or delete the old one |
Key takeaways
git initcreates an empty local repository, your starting point for any new projectgit clonecopies a remote repository with its whole history- The
.git/folder holds all of Git's machinery, do not delete it - Create a
.gitignorefrom the first commit to exclude unwanted files - Never commit secrets: passwords, API keys, tokens
- SSH is recommended for cloning: more secure and no password to type
- A bare repository has no working copy: it serves as a server, and you never work directly in it
Knowledge check
Check that you have grasped the essentials of this guide. The questions cover only what has just been explained here.
Knowledge check
Check what you have learned with this interactive quiz
How it works
- The timer starts when you click Start
- Multiple choice, true/false and short answer questions
- You can move between questions
- Detailed results are shown at the end
Starts the quiz and the timer
Review
(0/0)Score by domain
A domain groups several guides and gets several questions, so its score is more reliable than a per-topic score, which often rests on a single question.
Summary
Strengths
No topic passed at 80% on at least two questions yet.
Weak areas
No topic below the pass mark.
Recommended next
Hints before you try again?
Continue the course: Record changes in Git: add, commit and status
A new full quiz with random questions
Work again only on the questions you missed