Visualize a deep folder hierarchy

Northwind’s shared Drive has grown sideways for years. There are project folders inside client folders inside year folders, and nobody can say with confidence what lives where without clicking through it. When someone asks “where do the 2024 retainer contracts live?”, the honest answer is a shrug and five minutes of poking around.

This script walks the whole folder tree from a root you choose and writes it out as an indented outline in a Google Doc — a sitemap for your Drive. It is a read-only audit: it never moves or renames anything. Run it once to get your bearings, or re-run it every quarter to see how the structure has drifted.

What you’ll need

• The ID of the root folder you want to map. It is the long string in the folder’s URL after /folders/.
• Edit access to that folder and everything beneath it — the script can only list folders it is allowed to see.
• Nothing else. The script creates a fresh Doc each time and returns its URL.

The script

// The folder to start mapping from. The script walks everything beneath it.
const ROOT_FOLDER_ID = '1abcRootFolderId';

// Indent used per level of depth. Two spaces keeps deep trees readable.
const INDENT_UNIT = '  ';

// Safety cap on how deep the walk goes. Stops a runaway recursion if the
// tree is enormous or contains a shortcut loop.
const MAX_DEPTH = 25;

/**
 * Builds an indented outline of a folder tree and writes it to a new Doc.
 * Returns the URL of the Doc so you can open it straight from the log.
 */
function buildFolderSitemap() {
  // 1. Resolve the root folder. Bail out early if the ID is wrong.
  let root;
  try {
    root = DriveApp.getFolderById(ROOT_FOLDER_ID);
  } catch (err) {
    Logger.log('Could not open the root folder — check ROOT_FOLDER_ID.');
    return;
  }

  // 2. Create a dated Doc to hold the map.
  const stamp = new Date().toISOString().slice(0, 10);
  const doc = DocumentApp.create(`Folder map — ${stamp}`);
  const body = doc.getBody();
  body.appendParagraph(`Folder map for "${root.getName()}"`)
    .setHeading(DocumentApp.ParagraphHeading.TITLE);

  // 3. Walk the tree depth-first, appending one line per folder.
  walk(root, body, 0);

  // 4. Save and hand back the URL.
  doc.saveAndClose();
  Logger.log('Folder map ready: ' + doc.getUrl());
  return doc.getUrl();
}

/**
 * Recursively appends a folder and its sub-folders to the Doc body.
 * Each level is indented one INDENT_UNIT deeper than its parent.
 */
function walk(folder, body, depth) {
  // Stop if we have gone deeper than the safety cap allows.
  if (depth > MAX_DEPTH) {
    body.appendParagraph(`${INDENT_UNIT.repeat(depth)}… (max depth reached)`);
    return;
  }

  // Append this folder's name, indented to match its depth.
  body.appendParagraph(`${INDENT_UNIT.repeat(depth)}📁 ${folder.getName()}`);

  // Recurse into every sub-folder, one level deeper.
  const subs = folder.getFolders();
  while (subs.hasNext()) {
    walk(subs.next(), body, depth + 1);
  }
}

How it works

1. buildFolderSitemap resolves ROOT_FOLDER_ID inside a try/catch. A wrong or inaccessible ID is the most common failure, so it logs a clear message and stops rather than throwing a cryptic error.
2. It creates a new Doc named Folder map — <date> and adds a title paragraph naming the root folder.
3. It calls walk starting at depth 0. walk is recursive: it appends the current folder’s name, then calls itself for every sub-folder, increasing the depth by one each time.
4. The indent is INDENT_UNIT repeated depth times, so a folder three levels down is indented six spaces. MAX_DEPTH guards against a runaway walk if the tree is unusually deep or contains a shortcut that points back up.
5. Once the walk finishes, the Doc is saved and its URL is logged and returned.

Example run

Suppose the root folder looks like this in Drive:

• Clients
  • Acme Ltd
    • 2024
    • 2025
  • Globex
    • Contracts

After a run, the Doc contains an indented outline:

Folder map for "Clients"

📁 Clients
  📁 Acme Ltd
    📁 2024
    📁 2025
  📁 Globex
    📁 Contracts

That is the whole structure on one page — easy to scan, easy to paste into a wiki, and easy to compare against last quarter’s map.

Run it

This is an on-demand audit, so run it by hand when you need a fresh picture:

1. In the Apps Script editor, select buildFolderSitemap and click Run.
2. Approve the authorisation prompt the first time.
3. Open the URL from the execution log to read the map.

Watch out for

• The script lists folders only, not the files inside them. That keeps deep trees readable; if you also want file names, use Generate a shareable file-index Doc on the folders that matter.
• Very large trees can hit the six-minute execution limit. If the run times out, map a sub-folder at a time, or raise the root one level down.
• MAX_DEPTH is a safety net, not a real limit. If your tree legitimately goes deeper than 25 levels, raise the constant — but a tree that deep is usually a sign the structure itself needs flattening.
• Shortcuts to folders are not the same as folders. getFolders() returns real sub-folders only, so a tree that relies heavily on shortcuts will look thinner on the map than it does in the Drive UI.