Skip to content
Français
Account: not signed in, sync available My learning
Select theme
Français

By updated

Improve this page

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

  1. Create the folder and initialize it:

    Terminal window
    git init my-portfolio

    Expected output:

    Initialized empty Git repository in /home/bob/Projets/my-portfolio/.git/
  2. Enter the project:

    Terminal window
    cd my-portfolio
  3. Check that Git is active:

    Terminal window
    git status

    Expected output:

    On branch main
    No commits yet
    nothing 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:

Terminal window
cd my-existing-project
git init

Git 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:

Terminal window
cat > .gitignore << 'EOF'
# Dependencies
node_modules/
vendor/
.venv/
# Build files
dist/
build/
*.o
# Editors and IDEs
.vscode/
.idea/
*.swp
# Secrets (NEVER commit)
.env
*.key
*.pem
EOF

Clone 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.

Terminal window
git clone git@github.com:username/my-project.git

Replace 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:

Terminal window
git clone https://github.com/octocat/Hello-World.git

Here 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

OptionUseExample
<folder>Rename the local foldergit clone url my-folder
--depth 1Shallow clone (latest commit only)Useful for very large repositories
--branch <name>Clone a specific branchgit clone --branch develop url
--recurse-submodulesInclude submodulesProjects with Git dependencies

Example of a clone into a custom folder:

Terminal window
git clone https://github.com/octocat/Hello-World.git my-folder

Git 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):

Terminal window
ls -la .git/

Expected output:

total 40
drwxrwxr-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 HEAD
drwxrwxr-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 description
drwxrwxr-x 2 bob bob 4096 Nov 15 18:46 hooks
drwxrwxr-x 2 bob bob 4096 Nov 15 18:46 info
drwxrwxr-x 4 bob bob 4096 Nov 15 18:46 objects
drwxrwxr-x 4 bob bob 4096 Nov 15 18:46 refs

Each item has a precise role:

File / FolderRole
HEADPoints to the current branch (e.g. ref: refs/heads/main)
configLocal 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:

CharacteristicNormal repositoryBare repository
Working copyYes (your files)No
.git/ folderSubfolder of the projectThe whole project
UseDaily developmentServer (hosting)
Created withgit initgit 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.

Terminal window
git init --bare my-server.git
ls my-server.git

The 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/
HEAD
branches
config
description
hooks
info
objects
refs

For 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

SymptomLikely causeSolution
fatal: not a git repositoryYou 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 cloneSSH key not set upFollow the SSH section of the installation guide
HTTPS clone asks for a passwordPersonal token requiredGitHub 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 branchinit.defaultBranch not setgit config --global init.defaultBranch main
fatal: destination path ... already existsThe target folder already exists and is not emptyClone into another folder (last argument of git clone) or delete the old one

Key takeaways

  • git init creates an empty local repository, your starting point for any new project
  • git clone copies a remote repository with its whole history
  • The .git/ folder holds all of Git's machinery, do not delete it
  • Create a .gitignore from 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

10 questions
6 min
70% to pass

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