Programming and IT

git clone

git clone takes an entire repository from a server — with all its history, branches and tags — and puts a copy into a new folder on your computer. It is how you start working on any existing project, yours or someone else's.

Updated
In this article

What happens when you clone#

Cloning does three things in one go. It creates a folder, downloads the hidden .git directory with the whole commit history and every branch into it, and then lays out the files of the latest version next to it — the so-called working directory. The copy is complete: you can browse history offline, create branches and make commits even when the server is unreachable.

Git also remembers the address it got the data from under the name origin, and that name is used by default in every command that talks to the server. You clone a repository once; to get fresh commits you use git pull, not another clone.

Syntax and options#

git clone <url> [folder]

The address comes in three kinds: https://… (the simplest — you are asked for a password or token on your first push), git@server:owner/project.git (using an SSH key) and a plain path to a folder on disk. If you do not name the folder, Git takes the last part of the address without .git.

Option What it is for
-b <name>, --branch <name> check out the named branch instead of the default one; a tag works too
--depth <N> download only the last N commits instead of the whole history
--single-branch fetch one branch, not all of them
--recurse-submodules fetch nested repositories straight away
--filter=blob:none full history, but old file versions are fetched on demand
-o <name> call the source something other than origin
--bare a copy without working files, only the repository data

Example: an ordinary copy#

git clone https://github.com/example/notes.git

Cloning into 'notes'...
remote: Enumerating objects: 214, done.
remote: Counting objects: 100% (214/214), done.
remote: Compressing objects: 100% (128/128), done.
remote: Total 214 (delta 71), reused 205 (delta 66)
Receiving objects: 100% (214/214), 46.21 KiB | 3.85 MiB/s, done.
Resolving deltas: 100% (71/71), done.

A notes folder has appeared. To check that the link to the server was saved:

cd notes
git remote -v

origin	https://github.com/example/notes.git (fetch)
origin	https://github.com/example/notes.git (push)

Example: a fast copy without history#

When you only need the current code — say, to build the project — there is no point in pulling ten years of history:

git clone --depth 1 --branch release https://github.com/example/notes.git notes-build

The folder is called notes-build and contains a single commit of the release branch. This is called a shallow clone: some history commands will not work in it. If you do need the history later, fetch the rest:

git fetch --unshallow

One subtlety: if you pass a tag rather than a branch to --branch, Git leaves HEAD detached and says so honestly. To keep working you need a branch — how to create one is covered in the article on git branch.

When cloning fails#

fatal: destination path 'notes' already exists and is not an empty directory — a folder with that name already exists and is not empty. Either give a different name as the last argument or remove the old folder.

Repository not found or fatal: repository '…' not found — most often a typo in the address, but for private repositories a denied access looks exactly the same: the server does not even confirm the existence of what it will not show you.

Permission denied (publickey) — your SSH key was not accepted. For a one-off copy it is easier to use the https address of the same repository.

error: RPC failed … the remote end hung up unexpectedly — the connection broke on a large repository. --depth 1 followed by git fetch --unshallow usually helps.

How to undo a clone#

There is nothing to undo: a clone is a new folder and changes nothing else on your system. You delete a failed or unneeded copy together with its folder (rm -rf notes), and if you deleted it by mistake you simply clone again — all the commits are on the server. The only things lost with the folder are your uncommitted edits and branches you never pushed anywhere.

The other first-day commands are collected in the Git commands cheat sheet.

Step-by-step plan

  1. Get the repository addressOn the project page use the Code or Clone button; https is simpler, SSH needs a key.
  2. Pick a folderGo to the directory where the copy should appear: the clone creates a subfolder in it.
  3. Run git cloneWait for the Receiving objects and Resolving deltas lines — that is the end of the download.
  4. Go inside and checkcd into the folder, then git remote -v and git log --oneline -5: the address is saved, the history is there.
  5. Decide on depthOnly need the code — --depth 1; need the history — an ordinary clone.

Start learning this in your own space

The plan goes into your repository: tick off stages, keep notes — the change history shows how far you have come.

Start the plan

Check yourself

1.Which command puts a copy of the repository into a folder called work instead of notes?

2.What does the --depth 1 option do?

3.Under what name does Git save the address you cloned from?

Sources

Was this helpful?

More articles

Programming and IT Git branches A Git branch is a movable pointer to a commit, not a copy of your files. That is why creating one costs nothing, and the git branch command is what you use to list, create, rename and delete branches. Programming and IT How to create a repository from scratch A repository is your project folder plus a hidden `.git` folder that stores the whole history. One command creates it, but between that command and your first meaningful commit there are a few steps that are hard to redo later — the branch name, the list of ignored files and the link to a server. Programming and IT git push Until you run git push, your commits exist only on your own disk. The command sends them to a remote repository and moves the branch pointer there — which is also why it is the command that most often refuses, when someone else got their work in first. Programming and IT git commit A commit is a saved state of your project with an author, a timestamp and a message. git commit takes what you selected beforehand with git add and writes it into history as one indivisible piece. Programming and IT git merge Merging brings work from one branch into another. git merge takes the branch you name and joins its history with the current one — sometimes by just moving a pointer, sometimes by creating a separate commit, and sometimes by stopping and asking for help. Programming and IT git checkout Historically `git checkout` does several unrelated things at once: it moves your working copy to another branch, creates a branch and pulls a single file out of a commit. Because it was so overloaded, Git 2.23 added two separate commands — `switch` and `restore`. Here are both sides: the old way and its modern replacement.

More solutions

Obsidian alternative with sync An Obsidian vault is a folder of markdown files. Put it into a git repository on Skillok and you get sync between devices, the history of every edit and a way to read your notes in the browser — with links between notes, callouts and tags. Company knowledge base A company knowledge base rarely dies for lack of tools. It dies because nobody owns the pages and they quietly go out of date. Here is how to set up a base that has owners, a history and a clear way to change it. Personal knowledge base A personal knowledge base is not an archive of everything you have read. It is a set of your own notes, linked to each other, that you keep coming back to. Here is how to set one up so it works instead of turning into a dump of links.