GitHub

How to Create a Folder in GitHub From the Browser

How to Create a Folder in GitHub From the Browser

Open the repository, click Add file, choose Create new file, and type the folder name followed by a forward slash in the file name field. The folder shows up in the repository once the first file inside it is committed.

Git is the reason, not GitHub. According to the archived Git FAQ on the kernel.org wiki, Git stores files with their paths and doesn’t track a directory by itself.

So a folder with no files cannot be committed. Delete the last file in a folder and the folder goes with it.

This holds whichever tool you use. The web interface, GitHub Desktop, the command line and github.dev all want a file in the folder before it reaches the repository.

How to Create a Folder in GitHub From the Web Interface

YouTube player

There’s no create folder button. You create a file instead, and a forward slash typed in the file name field turns the text before it into a folder. After that it’s a normal commit.

  1. Open the repository’s main page, then browse to the folder where the new one should live (the repository root works too).
  2. Click the Add file dropdown above the file list and pick Create new file. The plus icon in the file tree on the left does the same thing.
  3. Type the folder name followed by a / in the file name field. The text turns into a path segment and the field resets for the next name.
  4. Type a file name after the slash, for example docs/README.md.
  5. Add a line or two of content to the file.
  6. Click Commit changes…, write a commit message and confirm.

GitHub Docs (October 2026) describes the slash as the directory separator for the file name field.

The file isn’t a side effect. It’s the reason the folder exists, and the section on why GitHub needs one goes into that further down.

Creating nested subfolders in one path

Typing docs/guides/setup.md gives you docs, a guides folder inside it, and the file, all in a single commit. Every extra slash is one more level.

The path starts in whichever folder you were browsing when you clicked Create new file. If the new folder belongs inside an existing one, browse there first.

Who Can Add a Folder, and Where Does the Commit Go?

Anyone with write access to the repository can commit a new folder directly. Everyone else sends it as a pull request from a fork.

Why is GitHub the heart of open source?

Uncover GitHub statistics: developer community growth, repository trends, collaboration patterns, and the platform that powers modern software development.

Explore GitHub Data →

With write access, you can commit to the current branch or put the commit on a new branch and open a pull request. Without it, GitHub forks the project to your personal account and helps you send a pull request after you commit (GitHub Docs, October 2026). Push rulesets are a separate matter. Rules set by the repository owner can block the new file outright, and they apply to every fork in the network.

The commit message comes next. GitHub Docs asks for a short, meaningful description of the change, so “Add docs folder with README” beats “update”.

If the account has more than one email address, a drop-down picks the author email, and only verified addresses show up.

Default branch or a new branch

When the current branch is the default branch, GitHub Docs recommends creating a new branch for the commit and opening a pull request. The final click is labeled either Commit changes or Propose changes.

RouteResultFits
Commit to the default branchFolder appears immediatelyPersonal repositories, solo work
New branch and pull requestFolder waits for a mergeTeam repositories, review rules
Fork and pull requestFolder lands in your fork firstRepositories you cannot write to

When a protected branch blocks the commit

GitHub Docs states that files in a protected branch cannot be edited or uploaded through the web interface. Required pull request reviews send every change through an approved pull request (GitHub Docs, October 2026), and repository admins skip these restrictions by default unless the setting that blocks bypassing is on.

Looking to sharpen your Git skills? Branching, merging, rebasing, and everything else you need - including git rebase, git stash, and commit workflows - is on one page in the Git Cheat Sheet.

A push ruleset can also reject the new file even when the branch itself is open.

Either way, the workaround is to commit to a new branch and open a pull request. The folder reaches the protected branch when the pull request merges.

Why Does GitHub Need a File Inside Every Folder?

A folder with no files gives Git nothing to store. Git keeps files together with their paths and never directories on their own, so on GitHub a folder exists only while it holds at least one committed file.

The archived Git FAQ on the kernel.org wiki traces this to the index, which lists files only. Directories get added automatically when the files inside them are added.

It doesn’t matter how you make the folder. One created with mkdir or in a file explorer stays on your machine after a push until a file goes inside it.

▶ GIT EXPLAINED

If you commit, branch, or merge code every day, it helps to know how Git came to be. This video covers how Linus Torvalds created Git in just 10 days after a license dispute and explains how its data model actually works.

Linus Torvalds Built Git in Days Out of Spite

It works in reverse too. Delete the last file in a folder and the folder disappears from the repository.

Which placeholder file do sources recommend?

Sources disagree on this one. The Git FAQ names .gitignore as a placeholder that works well, while Adam Johnson (2023) argues against .gitkeep because Git gives that name no special meaning.

DeployHQ’s guide pulls the other way. .gitkeep stays more common because the name states its purpose at a glance.

Nobody is really wrong here. .gitignore is a file Git documents, and .gitkeep is one people recognize.

The .gitkeep file

This one is a community convention, not a Git feature. The name states the purpose and the file is zero bytes, so there’s nothing to maintain. Most developers have seen it before.

Against that, Git has no documentation for it, and it turns into clutter once real files arrive.

A .gitignore placeholder

The Git FAQ recommends it, and Git documents the file, which counts for something. It can stay empty or list the files you don’t expect to see in the folder.

The downside is that an empty .gitignore reads like a mistake to the next person, and patterns inside it change what Git tracks in that folder.

Pick it when you want the placeholder to be a file Git itself explains.

README.md as the placeholder

A README.md turns the placeholder into documentation. It tells contributors what belongs in the folder, and because it carries real content it never looks like filler.

It goes stale, though, and it’s overkill for folders that tools fill, such as build output or logs.

If people will fill the folder, use README.md. If a build or script will, .gitkeep or .gitignore does the job.

How to Create a Folder With GitHub Desktop, the Command Line or github.dev

Local and browser-based editors all follow the same order of work: create the folder, put a file in it, stage, commit and push. What differs is the setup and how each one fails.

GitHub Desktop

  1. Open the cloned repository’s folder in your file manager (the Repository menu has a Show in Explorer or Show in Finder item).
  2. Create the new folder and put a file in it, such as README.md.
  3. Switch back to GitHub Desktop. The Changes tab lists the new file with a green icon, which marks an added file (GitHub Docs, October 2026).
  4. Type a summary, then click Commit to BRANCH.
  5. Click Push origin in the repository bar.

An empty folder never appears in the Changes tab, so Desktop shows no local changes until a file lands inside it.

If the branch is protected, Desktop warns you before the commit and offers a switch branches option.

Git command line

This runs in Git Bash on Windows or any shell on macOS and Linux, and it assumes the repository is already cloned.

  1. Make the folder and a starter file with mkdir docs, then touch docs/README.md.
  2. Stage it with git add docs.
  3. Commit with git commit -m "Add docs folder with README".
  4. Push with git push origin YOUR_BRANCH.

GitHub Docs (October 2026) uses the same stage, commit and push sequence for adding existing files.

Pushing straight to a branch that requires pull request reviews fails with error GH006. Push to a new branch and open a pull request instead.

github.dev and GitHub Codespaces

github.dev is the quick one. Press the period key on any repository page, or change github.com to github.dev in the URL. It runs in the browser, costs nothing and has no terminal (GitHub Docs, October 2026).

Add the folder from the explorer sidebar and put a file inside it. Then open the Source Control view, stage the file, type a message and click Commit & Push.

GitHub Codespaces is a dedicated VM with a terminal that behaves like a local one, plus a free monthly quota for personal accounts. Startup takes a few minutes, where github.dev opens instantly.

The same GitHub Docs page still labels github.dev a public preview. It also warns that heavy committing can hit an API rate limit, so wait a few minutes and retry.

How to Upload an Existing Folder to GitHub

YouTube player

Open the repository, choose Add file, then Upload files, or drag the folder straight into the browser window. GitHub Docs (October 2026) lists both routes, and both accept folders as well as single files.

Because the folder arrives with its files already inside, the placeholder question never comes up.

Browser upload limits

The browser caps what one upload can carry. These are the values GitHub Docs lists as of October 2026:

  • The browser accepts files up to 25 MiB.
  • A single upload takes at most 100 files.
  • Git warns above 50 MiB, but the push still succeeds.
  • GitHub blocks anything over 100 MiB, and Git LFS is the route beyond it.

The unit is MiB, not MB, so a 27 MB file is already over the browser limit.

What blocks an upload

Push protection blocks an upload that contains a supported secret, such as a token. Remove the secret and upload again. GitHub Docs still lists this check for web uploads as a public preview.

Uploads through the web interface also ignore .gitattributes, so automatic line ending conversion doesn’t run. Push with Git when those rules matter. For big binaries, GitHub Docs points to releases instead of tracking them in the repository.

Uploading from the command line instead

Copy the folder into the local clone, then run the same stage, commit and push sequence from the command line section above.

That route lifts the per-file browser ceiling and applies your .gitattributes rules, per GitHub Docs.

Which Method Should You Use?

Use the web interface for one new folder, and move to a local or browser-based editor once the job involves several. What decides it is how many files go into one commit.

MethodSetupTerminalCommit size
Web interfaceNone, browser onlyNoOne new file per commit (an upload carries up to 100)
GitHub DesktopInstall app, clone repositoryNoEverything you select
Git command lineGit installed, clone repositoryYesEverything you stage
github.devNone, press . on a repository pageNoEverything you stage
CodespacesCreate a codespace, a few minutes to startYesEverything you stage

The web interface suits a single new folder with one starter file, especially when you have no clone on hand. GitHub Desktop makes sense if the repository is already cloned and you’d rather click than type commands. Several folders in one commit, or a layout you script, belong on the command line.

github.dev handles several folders plus moving existing files, all from one browser tab. Codespaces is for work that needs a terminal when you don’t want to install anything locally.

Past one folder, the web interface costs more clicks than any other method.

Folder in GitHub FAQ

Is a folder in GitHub the same as a directory?

Yes. GitHub Docs (October 2026) uses both words, with subdirectories in the new file steps and Delete directory in the delete steps.

Tutorials say folder, the interface often says directory, and both name the same path container.

How do I move existing files into a folder?

Open the file, click the pencil icon to edit it, and type the destination folder followed by a / at the start of the file name field. Commit the change as usual.

Some files, such as images, cannot move this way and need the command line instead (GitHub Docs, October 2026).

Can I rename a folder in GitHub?

A rename means moving every file inside the folder to a new path, because Git tracks files and not directories. In the web interface that is one edit per file, which suits a folder with a handful of files.

For a larger folder, run git mv locally, then commit and push.

How do I delete a folder from a repository?

Open the folder, click the menu in the top-right corner and choose Delete directory. Review the listed files, write a commit message and commit.

Does deleting a folder remove its contents from Git history?

No. The deleting commit hides the files from the current branch, but earlier commits still hold them.

Sensitive data needs a history rewrite, which GitHub Docs covers under removing sensitive data from a repository.

Setting Up a Folder Structure Before the Repository Grows

A folder in GitHub costs one commit through the web interface, so a planned layout of several folders belongs in a single commit from a local clone or github.dev.

Order helps limit rework. Start by committing the first folder with a real file. Then create the remaining folders in one local or github.dev commit, and check repository size before any large upload.

The size check matters because folders organize files without shrinking a repository. GitHub Docs (October 2026) recommends repositories stay ideally under 1 GB, and strongly recommends under 5 GB.

One full browser upload of 100 files at 25 MiB each adds up to 2,500 MiB, roughly half of the 5 GB recommended maximum.

Batching folders into one commit trades per-folder history for fewer commits.

Each step was checked against GitHub Docs in October 2026. Both github.dev and push protection for web uploads still carry public preview labels, so their behavior can change.

Bogdan Sandu

Stay sharp. Ship better code.

Every week: one curated article, one tool worth knowing, one tip you can use tomorrow. No noise, no padding.