GitHub doesn't let you upload an empty folder, but you can create one by adding a file inside it

When you try to create a folder directly in GitHub's web interface, you'll find there's no "New Folder" button. This is because Git — the system GitHub runs on — only tracks files, not folders. A folder with nothing in it has nothing to track, so GitHub won't let you create it. The workaround is simple: add a file to the folder you want, and GitHub creates the folder automatically.

The most common approach is to add a placeholder file called .gitkeep inside the folder. This file does nothing except hold the folder in place. Once you push that file, the folder exists in your repository and you can add real files to it later.

Key Takeaways

  • GitHub creates folders automatically when you add a file inside them — you cannot create an empty folder directly.
  • The fastest method is to use GitHub's web interface to create a new file with a path that includes your folder name.
  • A .gitkeep file is a standard placeholder that holds a folder in place without adding anything meaningful to your project.
  • If you are working on your computer, you can create the folder locally, add a file to it, and push everything to GitHub in one step.

Adding a folder through GitHub's web interface

Open your repository on GitHub and click the "Add file" button near the top right. Select "Create new file" from the dropdown menu. In the filename field at the top, type the folder name followed by a forward slash and then the filename — for example, my-folder/.gitkeep. GitHub interprets the forward slash as a folder boundary and creates the folder structure automatically.

Type or paste any content into the file editor, or leave it blank if you are using .gitkeep as a placeholder. Scroll down to the "Commit new file" section, add a short message like "Add my-folder directory", and click "Commit new file". GitHub now shows the folder in your repository structure, and anyone who clones the repository will get that folder too.

This method works for nested folders as well. If you type docs/guides/getting-started.md, GitHub creates both the docs folder and the guides subfolder inside it, then places your file in the deepest level. All intermediate folders are created in one step.

Using .gitkeep as a placeholder

The .gitkeep file is a convention in the Git community — it is not a special GitHub feature, just a filename that developers recognize as a placeholder. The dot at the start makes it a hidden file on most systems, so it does not clutter your project. When you add .gitkeep to a folder, you are signaling to other developers that the folder is intentional and should be preserved.

You do not have to use .gitkeep. You could add a README.md file instead and write a description of what the folder will contain. You could add a .gitignore file if the folder will hold files you do not want to track. The point is that the folder must contain something, or GitHub will not create it.

Creating folders on your computer and pushing them

If you are working with Git on your computer, create the folder in your project directory the normal way — right-click and select "New Folder" on Windows, or use the terminal command mkdir folder-name on Mac or Linux. Then add a file inside it, such as a .gitkeep placeholder or an actual project file.

Open your terminal or command prompt, navigate to your project directory, and run git add . to stage all your changes. Then run git commit -m "Add folder-name directory" to create a commit, and git push to send it to GitHub. The folder and its contents now appear in your GitHub repository.

This approach is faster if you are creating multiple folders or adding many files at once, because you can set everything up locally and push it all in one batch rather than creating files one at a time through the web interface.

Organizing your repository with folders

Common folder structures depend on what your project does. A website might have css, js, and images folders. A Python project might have src for source code and tests for test files. A documentation site might have docs, guides, and api-reference. The structure you choose should make sense to someone opening your repository for the first time.

Add a README.md file in the root of your repository that explains what each folder contains. This saves people time and makes your project easier to navigate. If a folder will stay mostly empty for now, a .gitkeep placeholder keeps it visible and signals that it is part of your planned structure.

Deleting or renaming folders

To delete a folder through GitHub's web interface, you must delete all the files inside it one by one. Click on a file in the folder, click the trash icon, and commit the deletion. When the last file is gone, the folder disappears automatically. On your computer, you can delete the folder directly and push the change with git add . and git commit.

To rename a folder, delete all files in it, then recreate them in a new folder with the new name. Git does not track folder names directly — it only tracks file paths — so renaming a folder is really just moving files from one path to another. If you are doing this on your computer, you can use git mv old-folder/file.txt new-folder/file.txt to move files and preserve their history.

Frequently Asked Questions

Can I create a completely empty folder in GitHub?

No. Git only tracks files, not folders, so an empty folder has nothing to track. You must add at least one file to the folder for GitHub to create it. A .gitkeep placeholder is the standard way to hold a folder in place without adding meaningful content.

What is the difference between .gitkeep and .gitignore?

.gitkeep is a placeholder that holds an empty folder in place. .gitignore is a configuration file that tells Git which files to ignore and not track. You use .gitignore when you want to exclude certain files from your repository, such as temporary files or secrets. Both are hidden files that start with a dot.

Do I have to use .gitkeep, or can I use a different filename?

You can use any filename. .gitkeep is just a convention that developers recognize. Some people use README.md and write a description of the folder instead, or use .gitignore if the folder will hold files they do not want to track. The important thing is that the folder contains at least one file.

If I create a folder on my computer and push it, will it appear on GitHub?

Only if the folder contains at least one file. When you run git push, Git sends all the files you staged, and the folder structure is created based on the file paths. An empty folder on your computer will not be pushed to GitHub.

Can I create nested folders (folders inside folders) in one step?

Yes. When you create a new file through GitHub's web interface, type the full path with forward slashes, like docs/guides/tutorials/getting-started.md. GitHub creates all the intermediate folders automatically. The same works on your computer — just create the file in the nested location and push it.