How to Show the Top-Level Directory Structure of a Git Repository

Use git rev-parse --show-toplevel to locate the repository root, then pipe it to ls, tree, or Get-ChildItem depending on your operating system.

The every-app/open-seo repository is a full-stack TypeScript application organized with configuration files, source code, and deployment assets at its root. Whether you are troubleshooting deep inside nested directories or automating CI workflows, knowing the exact command to reveal the top-level directory structure of a Git repository saves time and prevents path errors.

Locate the Repository Root with Git

Git exposes the absolute path of the repository root through the rev-parse subcommand.

git rev-parse --show-toplevel

This outputs the directory containing the .git folder, regardless of your current working directory within the project. For the open-seo project, this might return /home/user/projects/open-seo or similar.

Why This Works

Git maintains a pointer to its metadata directory at the root of every repository. By invoking rev-parse with the --show-toplevel flag, you query this metadata to retrieve the canonical path. This is more reliable than manual navigation because it functions correctly from any subdirectory, including buried paths like src/serverFunctions/ or src/db/.

Cross-Platform Commands to List Top-Level Contents

Once you have the root path, pass it to a directory-listing utility to view the top-level structure without descending into sub-folders.

POSIX Systems (Linux/macOS)

List immediate children with ls, including hidden files:

git rev-parse --show-toplevel | xargs -I{} ls -1A "{}"

If you have the tree utility installed, generate a visual hierarchy limited to one level:

git rev-parse --show-toplevel | xargs -I{} tree -L 1 "{}"

Windows PowerShell

For Windows environments, use Get-ChildItem with the -Force flag to reveal hidden items:

git rev-parse --show-toplevel | ForEach-Object { Get-ChildItem -Force $_ }

JSON Output for Scripting

When building automation or reporting tools, emit structured JSON containing the root path and its entries:

ROOT=$(git rev-parse --show-toplevel)
printf '{"root":"%s","entries":["'$(ls -1A "$ROOT" | paste -sd '","' -)'"]}' "$ROOT"

This produces output like {"root":"/path/to/repo","entries":[".git","README.md","package.json"]}, which integrates easily with downstream processing.

Anatomy of the every-app/open-seo Repository

Running these commands against the every-app/open-seo clone reveals a full-stack TypeScript layout. The root contains:

• package.json – Defines runtime and dev dependencies, plus build scripts.
• vite.config.ts – Configures the Vite frontend build pipeline.
• wrangler.jsonc – Stores Cloudflare Workers configuration, including API bindings.
• compose.yaml – Docker Compose definition for self-hosted deployments.
• README.md – Project overview and hosting instructions.
• src/ – Core application code, including src/serverFunctions/ for SEO data handlers and src/db/schema.ts for Drizzle-ORM table definitions.
• docs/ – Documentation such as docs/SELF_HOSTING_DOCKER.md.

This structure demonstrates how the repository separates configuration, documentation, and source code at the top level.

Summary

• git rev-parse --show-toplevel returns the absolute path of the repository root from any location within the working tree.
• Pipe this path to ls -1A, tree -L 1, or Get-ChildItem to inspect top-level files without recursing into subdirectories.
• These commands work reliably in CI pipelines and local development shells, regardless of your current subdirectory.
• The every-app/open-seo repository exemplifies a standard layout with configuration files (package.json, vite.config.ts, wrangler.jsonc), documentation (README.md), and source code (src/) at the root.

Frequently Asked Questions

What is the fastest way to find the root of a Git repository?

Run git rev-parse --show-toplevel from any directory inside the project. This instantly returns the absolute path containing the .git directory, eliminating the need to traverse upward manually.

How do I list only the top-level files without entering subdirectories?

After obtaining the root with git rev-parse --show-toplevel, pipe it to ls -1A (POSIX) or tree -L 1 to restrict output to immediate children. This prevents listing the contents of folders like src/ or docs/ while still showing their names.

Can I use this command in a CI/CD pipeline?

Yes. git rev-parse --show-toplevel is exit-code stable and returns absolute paths, making it safe for shell scripts in GitHub Actions, GitLab CI, or Jenkins. Combine it with xargs or shell variable assignment to dynamically reference files at the repository root during build steps.

Does this work if I’m in a submodule?

When executed inside a Git submodule, git rev-parse --show-toplevel returns the root of that submodule, not the parent repository. This is usually the desired behavior for scripts specific to the submodule’s codebase.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}