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

> Discover the git command to show your repository's top-level directory structure. Easily list files and folders from the root with simple Git commands.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: how-to-guide
- Published: 2026-07-29

---

**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.

```bash
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:

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

```

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

```bash
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:

```powershell
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:

```bash
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`](https://github.com/every-app/open-seo/blob/main/package.json)** – Defines runtime and dev dependencies, plus build scripts.
- **[`vite.config.ts`](https://github.com/every-app/open-seo/blob/main/vite.config.ts)** – Configures the Vite frontend build pipeline.
- **`wrangler.jsonc`** – Stores Cloudflare Workers configuration, including API bindings.
- **[`compose.yaml`](https://github.com/every-app/open-seo/blob/main/compose.yaml)** – Docker Compose definition for self-hosted deployments.
- **[`README.md`](https://github.com/every-app/open-seo/blob/main/README.md)** – Project overview and hosting instructions.
- **`src/`** – Core application code, including `src/serverFunctions/` for SEO data handlers and [`src/db/schema.ts`](https://github.com/every-app/open-seo/blob/main/src/db/schema.ts) for Drizzle-ORM table definitions.
- **`docs/`** – Documentation such as [`docs/SELF_HOSTING_DOCKER.md`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/package.json), [`vite.config.ts`](https://github.com/every-app/open-seo/blob/main/vite.config.ts), `wrangler.jsonc`), documentation ([`README.md`](https://github.com/every-app/open-seo/blob/main/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.