How to organize folders inside a GitHub repo?

 

Step 1: Create a New Repository or Clone an Existing One

 

To start organizing folders, you first need a local copy of your GitHub repository. If you haven’t created one yet, head over to GitHub and initialize a new repository. Otherwise, clone an existing repository to your machine.

• Initialize a new repository on GitHub via the web interface.
• Clone your repository locally.

git clone https://github.com/your-username/your-repo.git
cd your-repo

 

Step 2: Plan Your Folder Structure

 

Before creating folders, map out how you want to organize your project. Common patterns include separating source code, documentation, tests, and assets.

• src/ – application or library source files
• docs/ – markdown documentation or design specs
• tests/ – automated tests, fixtures, and test data
• assets/ – images, logos, or other media
• scripts/ – utility or deployment scripts

 

Step 3: Create Folders Locally

 

Use the mkdir command to create folders in one go. The -p flag lets you build nested directories in a single command.

mkdir -p src docs tests assets scripts

If you need deeper nesting, run:

mkdir -p src/components/header
mkdir -p src/components/footer

 

Step 4: Add README Files to Each Folder

 

Including a README.md in each major folder helps explain its purpose to contributors.

touch src/README.md
touch docs/README.md
touch tests/README.md
touch assets/README.md

Inside each README, document:

• What the folder contains
• How files inside it are organized
• Any conventions contributors should follow

 

Step 5: Stage, Commit, and Push Your Changes

 

Once your folders and README files are in place, add them to Git, commit with a clear message, and push to GitHub.

git add .
git commit -m "Initialize organized folder structure"
git push origin main

 

Step 6: Verify the Structure on GitHub

 

Open your repository on GitHub and navigate through the folders to ensure everything appears as expected. You should see your top-level folders and their respective README files.

• Click on each directory in the web UI.
• Confirm that nested folders are displayed correctly.
• Review README previews to verify formatting.

 

Step 7: Maintain and Evolve Your Folder Organization

 

As your project grows, revisit your structure periodically. Keep directories focused and avoid deeply nested hierarchies that become hard to navigate.

• Refactor poorly named folders or relocate files when patterns emerge.
• Archive or remove unused directories to reduce clutter.
• Update README files to reflect any structural changes.