Git error - Fatal: Not a git repository

{{text-cta}}

What does “fatal: not a git repository” mean?

This error means you attempted to run a Git command, but weren’t inside a Git repository. Make sure you’ve:

• Navigated to the right directory. Check with `ls`.
• Initialized your repository with `git init` or by cloning an existing repo.
  

Usually, this is enough to fix the error. However, if that doesn’t do it, or you’re just curious about what it all means, let’s dig in.

A Git command needs to be run on a specific repository, so this error typically occurs when a Git command is run in a directory that Git doesn’t know about. In these cases, the fix is to make sure that you are both working in the correct folder and that you set up your repository right.

You can check if you’re working in the correct directory by running `ls` (or, for Windows, `dir`) -- this will output a list of folders and files in your current working directory, and should give you enough context to figure out if you’re in the right place. If you’re not, you can `cd` (change directory) to reach the right one

Once you’re in the right directory, you’ll want to make sure your repository is set up correctly. The most common reason for this error is that you actually haven’t set up your Git repository at all -- if that’s the case, you’ll want to run `git init` to kick off that process (read more about that in the official Git documentation here).

If that doesn’t solve the problem, there’s actually another way this error can be triggered -- if your HEAD file is corrupted. We’ll cover this later -- but first, a bit of background information.

How do Git repositories work?

A Git repository is a folder with a .git folder as a direct child. That .git folder contains all the information about your repository, including a history of all changes, the current branch you’re working on, and all the other information Git tracks.

Whenever you run a Git command, the first thing it does is check to see if you’re working in a valid Git repository by looking for that .git folder. If it finds that folder, then you’re all set and it moves to the next phase of running that command. If it can’t find that folder, however, Git has no context in which to operate. It doesn’t know anything about your project, so it throws a fit.

The reason for the (or any of the parent directories) part of the error is that Git will actually travel up the directory tree to the root of your computer looking for that `.git` folder. In plain English, it checks the folder that you’re currently in, and then the folder containing that folder, and so on, up as far as possible.

That’s why, if you’re working in a Git repository, you can `cd` into a child folder and still be able to run Git commands just fine.

Note: if you create a Git repository inside another repository, Git will treat that repository independently of its parent. In other words, Git will use the first `.git` folder it finds and treat its parent folder, along with all that folders children, as the current repository.

{{text-cta}}

How to really know you’re in a Git repository

Generally speaking, you can get a Git repository locally in one of two ways. One way is to run the `git clone` command and clone a repository from an existing repository (whether that repository exists locally on your computer or on a server running Git such as GitHub.com). The other way is to initialize a new Git repository using the `git init` command to set up version tracking in a new folder.

Either way, that `.git` folder I mentioned should exist in the repository’s root (top-most folder). If `ls` and seeing your project’s folders isn’t enough for you, there’s another technique to be even more sure that you’re in the right place. That period in front of the `.git` folder means that it’s actually a hidden folder, so it won’t show up in your Finder or Explorer window and is typically only meant for scripts and OS-level commands to access.

With a bit of magic, though, we can see it ourselves. You just need to add a flag to the `ls` command that will ask it to show hidden folders, and that’s the `-laf` flag.
The command looks like this:

As you can see, that command spat out a list of local files and folders with a bunch of extra gobbledegook, arranged into a table. The most important folder we’re looking for is that `.git` folder. If you see it, that means you’re in a Git repository.

If that doesn’t fix it, check your HEAD file

As I mentioned at the beginning of this article, there’s another way this exact error can occur: if your HEAD file is corrupted.

The HEAD file is a file that sits directly in the `.git` directory, and it contains some information that points Git to the current branch that you’re working on. If your HEAD file is somehow emptied or corrupted, you’ll start seeing the exact same error, even though you are currently in a correctly initialized repository.

To check that the HEAD file contains the correct contents, you can run the `cat` command:

If this produces an unexpected result, figure out which branch you’re working in and then put that into the HEAD file.

Read more about the HEAD file here, including what format the contents should be in. Good luck!