In the previous lesson Ana turned her folder into a repository and created the project's first commit. She has worked on it for a few more days since then, and the history of task-manager already holds several commits. The team has also published the repository on an internal server so that it can be shared.

Today Bruno joins, and he works on macOS. Bruno needs the project on his laptop, but not just any copy: he needs the files and the whole history, so that he can look up why each change was made, compare versions and, later on, contribute his own. Downloading a .zip would give him today's files and nothing else: no history, no context, no ability to collaborate.

The right tool is git clone. In this lesson we will see what it really does — which is quite a bit more than copying files — which protocols exist for reaching a remote repository and how they differ, the options that come up most in daily work (--branch, --depth, --single-branch) and, above all, when to use clone and when to use init, a classic beginner's doubt.

1. Bruno's situation
2. git clone in its simplest form
3. What git clone really does, step by step
4. Protocols: HTTPS, SSH and a local path
5. Cloning into a directory with a different name
6. Cloning a specific branch with --branch
7. Shallow clones with --depth
8. --single-branch and other useful options
9. init versus clone: the conceptual difference
10. Checks to run after cloning

The task-manager repository is published on the company's internal server. Bruno has three possible addresses for reaching it:

All three point at the same repository: a bare repository — no working tree, as we saw at the end of the previous lesson — acting as the team's central point. How Ana's repository got there, and how these addresses are managed, is the subject of module 4; here we focus on the other side of the operation: bringing it home.

Bruno already has Git installed and configured with his identity, following what we saw in module 1:

Bruno moves into the folder where he keeps his projects and runs:

And that is it: in a few seconds he has the complete project.

There is Ana's complete history, including the initial commit we created in the previous lesson and the recurring commit "Add task deletion to the list" touching app.js. Bruno has not received a photograph of the project: he has received the project and its memory.

And the working tree is clean from the very first moment:

The lines that scroll past during the download are not noise; they describe what the server is doing:

That (delta 6) connects with something we mentioned in The Git Data Model: conceptually Git stores snapshots, but to store and transmit them it uses packfiles, which do compress some objects against others. It is an invisible optimisation: once Resolving deltas finishes, Bruno's disk holds exactly the same objects as Ana's.

A clone looks like a simple "download the folder", but it is five chained operations. Understanding them heads off an enormous amount of later confusion.

Unless you say otherwise, Git uses the last segment of the URL without the .git suffix. From https://git.example.com/team/task-manager.git comes the folder task-manager. If that folder already exists and is not empty, the clone fails:

This is a deliberate safeguard: git clone never overwrites existing work.

Internally, a clone starts by doing the equivalent of git init in the destination directory. That is why the result has exactly the same anatomy we studied yesterday:

A few items show up that a plain git init did not produce — index, logs/, packed-refs, FETCH_HEAD — simply because here there is actual content: there are staged files, there are references to pack and a network operation has taken place.

This is where the important part happens. Git downloads the entire object database: every blob, every tree, every commit and every tag in the source repository, together with its references.

This is what makes Git a distributed system, as we saw in What is Git?: after the clone, Bruno's laptop holds a complete, fully functional copy of the project. He can browse the history, compare versions from a year ago or create commits with no network connection. In a centralised system such as SVN, almost any of those operations would require talking to the server.

We can verify it:

All 24 objects are there, inside a packfile (in-pack: 24).

The clone records where it came from, under the conventional name origin:

And it writes it into the repository's local configuration:

origin is not a reserved word in Git: it is merely the default name clone gives the remote. You could call it central, upstream or server. The convention is so well established that it is worth sticking to.

The [branch "main"] section means the local branch main tracks origin/main. That is what lets git status tell you whether you are ahead of or behind the server. All of this — remotes, tracking branches, fetch, pull, push — is the content of module 4; here it is enough to know that the clone sets it up on its own.

Finally, Git creates a local branch matching the source's default branch (main), points HEAD at it and writes that commit's files to disk, populating the working tree and the staging area at the same time.

That last detail explains why git status comes out clean straight after a clone: all three areas — repository, staging area and working tree — hold the very same content.

The URL you hand to git clone determines how the data travels. These are the three cases you will meet in practice:

It is the most universal option because port 443 is open practically everywhere. Cloning a private repository will ask you for credentials:

One important warning: on modern platforms (GitHub, GitLab and the like) that "password" is not your account password but a personal access token. To avoid retyping it every time, use the credential.helper we configured in Initial Configuration.

Notice that the short SSH form has no :// and uses a colon to separate the host from the path:

It relies on a pair of cryptographic keys: the public one is registered on the server and the private one stays on your machine. Once it is set up, cloning and working never ask for a password again. It is the preferred option for daily work. Generating the keys and registering them is covered in Authenticating with Remote Repositories.

There is also an equivalent long form, which does carry :// and lets you specify a port:

You can clone from a folder on your own disk or from a network-mounted share:

It is blindingly fast and needs neither network nor credentials. It has one useful quirk: when source and destination sit on the same filesystem, Git uses hard links for the objects instead of copying them, so the clone takes up almost no space. If you would rather have a genuinely independent copy:

And if you write the path with the file:// prefix, Git uses the same transfer machinery it would use against a remote server, which is handy for testing:

Careful when cloning from a non-bare repository. You can clone from a normal repository (straight from Ana's ~/projects/task-manager, for instance), and it works: you get the whole history. But you only get what has been committed: any changes Ana has left uncommitted in her working tree or staging area do not travel. This is a reliable source of surprises — "I cloned your repo and your last change is missing" almost always means "you had not committed it".

Just add the name you want as a second argument:

The repository is identical; only the folder holding it changes. This helps in three situations:

• Avoiding collisions: you already have a task-manager folder belonging to another project.
• Keeping two copies of the same repository, one to work in and another to consult an old version without disturbing the first. (For this particular case there is a purpose-built tool, git worktree, which you will meet in module 6.)
• Unhelpful names: if the repository is called web, you might prefer web-client-acme.

If you want to clone into the current directory rather than a new one, use . as the destination. The directory must be empty:

By default a clone leaves you sitting on the source's default branch (main). With --branch (or -b) you pick another one:

Two important clarifications:

1. The whole repository is downloaded anyway. --branch does not filter what arrives; it only decides which branch you land on. The others are still there, still reachable.
2. It accepts tags too. Hand it a tag name and you will get the exact content of that version, but in detached HEAD state (you will not be on any branch):

That is perfectly fine for inspecting a released version. Exactly what that state means and how to leave it belongs to Understanding Branches and Tagging Commits.

On a project with years of history, cloning the lot can mean downloading hundreds of megabytes you may not need. --depth limits how many commits come across:

Compare that with the full clone in section 2: 6 objects instead of 24. Only the latest commit has arrived.

The word grafted marks the point where the history is cut off artificially. That commit appears to have no parent, even though it does have one in the original repository.

Yes:

• Continuous integration. A CI server builds and throws the copy away; the history is dead weight to it. This is by far the most common use.
• Containers and deployment images, where every megabyte counts.
• A one-off look at an enormous project when all you want is today's code.

No:

• Your daily working copy. You lose blame, you lose bisect and you lose any comparison with the past — three of the reasons to use Git in the first place.

If you change your mind, there is no need to clone again:

Or fetch more depth than you currently have:

Both commands belong to module 4; we mention them here so that you know the decision is reversible.

A modern note. Recent versions of Git offer partial clones (--filter=blob:none), which download the whole commit graph but fetch file contents only when they are needed. They keep log, blame and bisect working and are usually a better choice than --depth for large repositories. We will look at them in Scaling Git for Large Projects.

--single-branch downloads only the branch you name, ignoring the rest:

Unlike --depth, it keeps the entire history of that branch; what it avoids is dragging in branches you do not care about. In a repository with two hundred working branches, the difference is noticeable.

An important note: --depth implies --single-branch automatically, unless you add --no-single-branch.

A round-up of the most frequent options:

A couple of worked examples:

This creates a bare repository holding every reference from the source, not just the branches. It is the usual way to migrate a repository from one server to another.

This is the most common confusion at the start, and one question settles it: does the project already exist somewhere?

Ana used init because the project was born with her. Bruno uses clone because the project already existed. Every person on the team will run clone once per project and per machine; init is run exactly once in the life of a project.

One frequent mistake deserves a mention of its own: running git init in an empty folder with the intention of "downloading" a project that already exists, and then trying to wire it up by hand. It is possible — add the remote and fetch, as we will see in module 4 — but it takes three steps where git clone takes one, and it is easy to end up misconfigured. If the project already exists, clone it.

These four checks take ten seconds and prevent misunderstandings:

And a fifth one, which matters most on a team using conditional profiles (includeIf) like the one we set up in Configuring Git:

Checking this before the first commit is far cheaper than fixing the authorship afterwards, which means rewriting the history.

• Cloning inside an existing repository. Run git clone without paying attention while you are inside another project and you end up with a nested repository that confuses both Git and your colleagues. Check with pwd first, or with git rev-parse --show-toplevel.
• Using --depth 1 for your daily working copy. You save a few seconds once and lose blame, bisect and every historical comparison for months. Keep it for CI and containers.
• Mixing up the SSH URL with the HTTPS one. git@host:group/repo.git is SSH (no ://, with a colon); https://host/group/repo.git is HTTPS. Copy the SSH one without having keys set up and the clone will fail with Permission denied (publickey).
• Believing that cloning also copies uncommitted work. A clone brings only what has been committed. If something is missing, it is almost always because it was never committed.
• Expecting .gitignore to make files disappear when you clone. A clone reproduces what is in the history. If an unwanted file was committed back in the day, it will arrive all the same; ignoring it now does not take it out of the past.
• Cloning a huge project over HTTPS on a slow network and assuming it has hung. Use git clone --progress, or add --depth if you genuinely do not need the history.
• Tip: if a clone fails halfway through, delete the half-created folder before retrying; otherwise the second attempt fails with destination path already exists.
• Tip: right after cloning, run git log --oneline -5 and skim the README. Two minutes there save you a round of questions to the team.

With no server and no network, reproduce the whole scenario. Starting from a repository with two commits standing in for Ana's:

1. Create ~/practice/ana/task-manager with a README.md and an app.js, and initialise it with two commits.
2. From it, create a bare repository at ~/practice/server/task-manager.git to act as the central point.
3. Clone it into ~/practice/bruno/task-manager, playing the part of Bruno.
4. Prove with commands that Bruno has: the two commits, the origin remote pointing at the bare repository, and the main branch tracking origin/main.

Using the bare repository from the previous exercise (extend it to five commits first so that the difference shows), make two clones: one full and one with --depth 1. Then:

1. Compare the number of objects in each.
2. Compare the output of git log --oneline.
3. Try running git log against a specific file in both and explain the difference.
4. Turn the shallow clone into a full one and check that it now behaves like the other.

For each situation, state the exact command you would use and briefly justify why. There is a deliberate trap in the list.

1. Carla starts today and needs task-manager on her Windows 11 machine, with the full history, for daily work.
2. The continuous integration server must build the latest version of main on every change, as fast as possible.
3. Ana wants to start a new project, monthly-reports, which does not exist anywhere yet.
4. Bruno needs to look at what styles.css was like in the version tagged v1.0, without interrupting his work in his current copy.
5. The team is moving to a new server and the whole repository must go with it, branches and tags included.
6. Carla already has a task-manager folder holding the project as downloaded in a .zip from a colleague, and wants to "connect" it to the team repository.

Solution to Exercise 1

Step 1 — Ana's repository:

Step 2 — the central bare repository:

--bare creates the replica with no working tree, which is exactly what a central repository should be:

Step 3 — Bruno's clone:

Step 4 — the three demonstrations:

The hashes matching Ana's repository exactly is no coincidence: as we saw in The Git Data Model, the hash derives from the content, so copying objects between repositories preserves the identifiers. That is the foundation that lets Git synchronise different machines without ambiguity.

Solution to Exercise 2

First we extend Ana's history and carry it over to the bare repository (the mechanics of pushing changes belong to module 4, so here we solve it by cloning again):

The two clones:

(We use file:// because --depth has no effect on a direct local path: Git optimises that case by copying or linking the objects whole.)

1. Number of objects:

2. The history:

3. History of a single file:

The difference is not cosmetic: in the shallow clone the file appears to have sprung into existence, complete, in the last commit. Any investigation into when a line was introduced — git log, git blame or git bisect — will give a false answer. That is why --depth is for building, not for investigating.

4. Turning it into a full clone:

grafted is gone and the history matches that of the full clone.

Solution to Exercise 3

1. Carla joins:

A plain, full clone. This is her daily working copy, so no --depth: she will need blame and the history. SSH if she has keys set up; HTTPS if she does not yet.

2. Continuous integration server:

This is the textbook case for a shallow clone: it builds and discards, the history adds nothing and the download is kept to a minimum. HTTPS with a token is the norm in CI because it avoids managing SSH keys.

3. A new project:

There is nothing to clone: the project is born here. git init <name> creates the folder into the bargain.

4. Inspecting version v1.0 without disturbing current work:

A second clone in another folder under another name leaves his working copy untouched. It will sit in detached HEAD, which is fine for reading. (A neater alternative he will meet in module 6: git worktree add.)

5. Server migration:

--mirror is the right option here, not plain --bare: it replicates every reference — branches, tags and remote references — and not just the local branches. It is the standard way to move a repository wholesale between servers.

6. The trap. Here you must not clone over the existing folder, and in fact Git would not let you: git clone demands an empty or non-existent directory. But the underlying problem is a different one: Carla's folder came from a .zip, so it has no history and no relationship whatsoever with the team repository. Wiring it up by hand would only breed conflicts and confusion.

The right answer is to set that folder aside and clone properly:

If Carla had made changes in the .zip copy, she copies them by hand into the fresh clone and commits them there as ordinary changes. The general rule: a folder downloaded as a .zip is not a repository and git init does not turn it into one; to join an existing project, you clone.

Bruno is now part of the project. In this lesson we have seen that:

• git clone does five things, not one: it creates the directory, initialises it, downloads the whole object database, registers the source as the remote origin, and creates the local branch, writing its files out to the working tree.
• A clone brings the complete history, and that is the essence of the distributed model: Bruno can browse, compare and commit with no network.
• There are three common protocols: HTTPS (universal, with a token), SSH (comfortable day to day, with keys) and a local path (instant, for copies and testing). You can tell them apart at a glance from the shape of the URL.
• You can choose the directory name, the target branch with --branch and how much history with --depth.
• Shallow clones are excellent for CI and terrible for working, because they break log, blame and bisect. The decision is reversible with git fetch --unshallow.
• init and clone answer different questions: init when the project is born with you, clone when you join one that already exists.
• A clone brings only what has been committed. Anything left uncommitted at the source stays behind.

Ana and Bruno each have their own repository now: one created hers, the other cloned his. From here on, both of them do exactly the same thing every single day: edit files, decide which changes belong together and record them in the history.

That cycle — edit, stage, commit — is Git's heartbeat and the subject of the next lesson, The Basic Git Workflow. There we will set in motion the three areas you have known since module 1, follow the complete life cycle of a file from the moment Git knows nothing about it until it is committed, and learn to read git status — in both its long and its short form — as the compass that tells you, at any moment, where you stand.