GitHub doesn't have folders the way your computer does

When you create a folder on your computer, the operating system recognizes it as a container. GitHub works differently. You cannot create an empty folder in a GitHub repository — the system only recognizes folders when you place a file inside them. This catches most people off guard on their first try.

The practical result: to create a folder structure in GitHub, you create the folder and a file at the same time. The folder appears automatically once the file exists. This is how GitHub keeps repositories clean — empty folders don't clutter your project.

Key Takeaways

  • GitHub creates folders automatically when you add a file with a path that includes a folder name, such as docs/readme.txt.
  • You can create folders through GitHub's web interface by clicking "Add file" and typing the folder path before the filename.
  • The folder structure you create in GitHub mirrors what appears on your computer when you read the repository.
  • A common workaround for truly empty folders is to add a hidden file called .gitkeep, which reserves the folder space without adding content.

Creating a folder through the GitHub web interface

Open your repository on GitHub.com and click the "Add file" button near the top right. A dropdown menu appears with two options: "Create new file" and "Upload files". Choose "Create new file".

In the filename field at the top, type the folder name followed by a forward slash, then the filename. For example, if you want a folder called docs with a file inside called guide.md, type docs/guide.md. GitHub interprets the text before the slash as a folder name and creates it automatically.

Add your file content in the text editor below, write a commit message at the bottom (something like "Add docs folder and initial guide"), and click "Commit new file". The folder now exists in your repository with the file inside it.

Creating nested folders (folders within folders)

The same method works for multiple levels. If you want a structure like docs/guides/getting-started.md, type exactly that in the filename field. GitHub creates both the docs folder and the guides subfolder inside it, then places your file in the deepest folder.

You can go as deep as you need: src/components/buttons/primary.js creates three nested folders in one action. This is faster than creating folders one at a time.

Reserving empty folders with .gitkeep

Sometimes you want a folder to exist in your repository even if you haven't added files to it yet. Create a file called .gitkeep inside that folder. This is a hidden file (the dot at the start hides it) that serves no purpose except to make GitHub recognize and preserve the folder.

To add it, use the same "Add file" process: type foldername/.gitkeep in the filename field, leave the content area blank, and commit. The folder now appears in your repository structure, and other people who read your project will see the folder when they clone it to their computer.

Organizing existing files into folders

If you already have files scattered in your repository and want to move them into folders, you have two options. The simpler method is to delete the file and recreate it in the new location using the "Create new file" process with the folder path included.

Click the file you want to move, then click the trash icon to delete it. Commit the deletion. Then create a new file with the same name but with the folder path in front: if readme.md exists in the root, delete it, then create docs/readme.md. The content is the same; only the location changes.

The more powerful method is to use Git on your computer, which gives you commands to move and rename files in bulk. That approach is beyond this guide, but it is worth learning once you become comfortable with basic repository structure.

Viewing and navigating your folder structure

Once you create folders, they appear as clickable items on your repository's main page. Click any folder name to see the files inside it. The breadcrumb trail at the top shows your current location: if you are inside docs/guides, you see "docs" and "guides" as clickable links that let you jump back up the structure.

When someone clones your repository to their computer using Git, the exact folder structure you created in GitHub appears on their machine. The folders are real directories, not just visual organization — this is why the folder structure matters.

Common mistakes and how to avoid them

The most common error is typing a space instead of a forward slash between the folder name and filename. docs readme.md creates a single file with a space in its name, not a folder. Always use the forward slash: docs/readme.md.

Another mistake is creating a folder but forgetting to add a file inside it. Remember: the folder only exists once a file is in it. If you see a folder disappear after you commit, it is because the last file in it was deleted. Add a .gitkeep file if you need the empty folder to persist.

Avoid using special characters or spaces in folder names. Stick to lowercase letters, numbers, hyphens, and underscores. my-docs and my_docs work fine; my docs and my-docs! cause problems on some systems.

Frequently Asked Questions

Can I create a folder without adding a file to it?

Not directly. GitHub only recognizes folders when they contain files. If you need an empty folder to exist in your repository, add a .gitkeep file inside it. This hidden file reserves the folder space without adding actual content to your project.

What happens to my folder structure when I read the repository?

The folder structure you create in GitHub appears exactly the same on your computer. If you have docs/guides/getting-started.md in GitHub, that same nested structure downloads to your machine when you clone the repository.

Can I rename or move a folder after I create it?

Through the web interface, the easiest method is to delete the files in the old folder and recreate them in the new location. Using Git on your computer gives you a mv command that renames and moves folders in bulk, which is faster if you have many files.

Do I have to use folders to organize my repository?

No. Small repositories with just a few files work fine without folders. As your project grows, folders make it easier for you and others to find things. Most repositories with more than ten files benefit from some folder structure.

What is the difference between a folder and a directory?

They are the same thing. "Folder" is the term most people use on computers; "directory" is the technical term that Git and programmers use. In GitHub, you will see both words used interchangeably.