fix: clean up leftover gh-pages branch files (dotfiles, submodules)

gh-pages@6.3.0's "Removing files" step calls globby without `dot: true`,
so dotfiles (.gitignore, .gitmodules, .github/) and submodule gitlinks
from the gh-pages branch are not removed before our dist is copied on
top. They then get re-committed and leak into the deploy.

Upstream fix tschaub/gh-pages#612 (merged 2025-08-09) adds both
`remove: '**/*'` and `dot: true`, but is unreleased as of v6.3.0. We
can't reach the globby call from options alone.

Workaround: register a `beforeAdd` hook that runs after gh-pages'
broken remove + our file copy. The hook asks git what it still has
indexed (`git ls-files -z`), diffs against the set of files in our
dist, and `git rm`s the leftovers. `git rm` handles submodule gitlinks
correctly, so the `build` gitlink from the reporter's scenario is also
cleaned up.

Skipped when the user opts into `add: true` (additive mode explicitly
preserves existing files).

Adds a spawn-level regression test in engine.gh-pages-behavior.spec.ts
that mocks `git ls-files` to return leftover dotfiles + a submodule
gitlink, runs engine.run() end-to-end through real gh-pages, and
asserts `git rm` targets the leftovers while leaving dist files alone.

Fixes #204

Author: JohannesHoppe

src/engine/engine.gh-pages-behavior.spec.ts

@@ -53,7 +53,7 @@ function createMockChildProcess(): Partial<ChildProcess> {
  * This is intentional - we want to know about any new git operations.
  */
 const EXPECTED_GIT_COMMANDS = [
-  'clone', 'clean', 'fetch', 'checkout', 'ls-remote', 'reset',
+  'clone', 'clean', 'fetch', 'checkout', 'ls-remote', 'ls-files', 'reset',
   'rm', 'add', 'config', 'diff-index', 'commit', 'tag', 'push', 'update-ref'
 ];
 
@@ -1066,4 +1066,87 @@ describe('gh-pages v6.3.0 - behavioral snapshot', () => {
       expect(spawnCalls[0]?.args[0]).toBe('clone');
     });
   });
+
+  /**
+   * End-to-end regression for issue #204: gh-pages@6.3.0's "Removing files" step
+   * skips dotfiles and submodule gitlinks. Our beforeAdd hook should catch them
+   * via `git ls-files` and `git rm` the leftovers while leaving dist files alone.
+   */
+  describe('submodule / dotfile cleanup regression (issue #204)', () => {
+    const engine = require('./engine');
+    const { cleanupMonkeypatch } = require('./engine.prepare-options-helpers');
+    const { logging } = require('@angular-devkit/core');
+
+    beforeEach(() => {
+      cleanupMonkeypatch();
+    });
+
+    it('engine.run() should git rm leftover gh-pages branch files not present in dist', async () => {
+      const repo = 'https://github.com/owner/leftover-test.git';
+      currentTestContext.repo = repo;
+
+      const leftoverFiles = [
+        '.github/workflows/deploy.yml',
+        '.gitignore',
+        '.gitmodules',
+        'build' // submodule gitlink
+      ];
+
+      // Reconfigure the default mockSpawn so `git ls-files` returns our leftover set.
+      // Other git commands keep the outer describe's default behavior.
+      mockSpawn.mockImplementation((cmd: string, args: string[] | undefined, opts: unknown) => {
+        const capturedArgs = args || [];
+        spawnCalls.push({ cmd, args: capturedArgs, options: opts });
+
+        if (cmd === 'git' && capturedArgs[0] && !EXPECTED_GIT_COMMANDS.includes(capturedArgs[0])) {
+          throw new Error(`Unexpected git command: ${capturedArgs[0]}. Add to whitelist if intentional.`);
+        }
+
+        const child = createMockChildProcess();
+        setImmediate(() => {
+          let output = '';
+          if (cmd === 'git' && capturedArgs[0] === 'ls-files') {
+            output = leftoverFiles.join('\0') + '\0';
+          } else if (cmd === 'git' && capturedArgs[0] === 'config' &&
+                     capturedArgs[1] === '--get' && capturedArgs[2]?.startsWith('remote.')) {
+            output = repo;
+          } else if (cmd === 'git' && capturedArgs[0] === 'ls-remote') {
+            output = 'refs/heads/gh-pages';
+          } else if (cmd === 'git' && capturedArgs[0] === 'diff-index') {
+            child.emit!('close', 1);
+            return;
+          }
+          child.stdout!.emit('data', Buffer.from(output));
+          child.emit!('close', 0);
+        });
+        return child;
+      });
+
+      const options = {
+        repo,
+        branch: 'gh-pages',
+        dotfiles: true,
+        notfound: false,
+        nojekyll: false
+      };
+
+      await engine.run(basePath, options, new logging.NullLogger());
+
+      // Our hook should have issued `git ls-files -z`.
+      const lsFilesCall = spawnCalls.find(c => c.cmd === 'git' && c.args[0] === 'ls-files');
+      expect(lsFilesCall).toBeDefined();
+      expect(lsFilesCall!.args).toContain('-z');
+
+      // And a subsequent `git rm` that targets exactly the leftovers.
+      const rmCalls = spawnCalls.filter(c => c.cmd === 'git' && c.args[0] === 'rm');
+      const cleanupCall = rmCalls.find(c => leftoverFiles.every(f => c.args.includes(f)));
+      expect(cleanupCall).toBeDefined();
+
+      // Dist files (from the outer beforeAll: index.html, main.js, styles.css, .htaccess)
+      // must NOT be in the cleanup call — those are files we just copied.
+      for (const distFile of ['index.html', 'main.js', 'styles.css', '.htaccess']) {
+        expect(cleanupCall!.args).not.toContain(distFile);
+      }
+    });
+  });
 });

src/engine/engine.prepare-options-helpers.ts

@@ -6,6 +6,8 @@
  */
 
 import { logging } from '@angular-devkit/core';
+import * as fs from 'fs/promises';
+import * as path from 'path';
 import * as util from 'util';
 
 import { Schema } from '../deploy/schema';
@@ -225,6 +227,86 @@ export async function injectTokenIntoRepoUrl(options: PreparedOptions): Promise<
   }
 }
 
+/**
+ * Minimal subset of the gh-pages internal Git class that our cleanup hook relies on.
+ * See src/node_modules/gh-pages/lib/git.js — `Git.prototype.exec`, `Git.prototype.rm`, `cwd`, `output`.
+ */
+export interface GhPagesGit {
+  cwd: string;
+  output: string;
+  exec(...args: string[]): Promise<GhPagesGit>;
+  rm(files: string[]): Promise<GhPagesGit>;
+}
+
+/**
+ * Recursively walk a directory and return the set of relative file paths,
+ * using POSIX separators so the output matches what `git ls-files` prints.
+ * Honors the same dotfile-inclusion semantics as gh-pages' `options.dotfiles`.
+ */
+export async function collectDistFiles(
+  baseDir: string,
+  includeDotfiles: boolean
+): Promise<Set<string>> {
+  const files = new Set<string>();
+
+  async function walk(relDir: string): Promise<void> {
+    const fullDir = relDir ? path.join(baseDir, relDir) : baseDir;
+    const entries = await fs.readdir(fullDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!includeDotfiles && entry.name.startsWith('.')) {
+        continue;
+      }
+      const relPath = relDir ? `${relDir}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        await walk(relPath);
+      } else if (entry.isFile()) {
+        files.add(relPath);
+      }
+    }
+  }
+
+  await walk('');
+  return files;
+}
+
+/**
+ * Create a `beforeAdd` hook that removes leftover files from the gh-pages branch
+ * before gh-pages stages our dist for commit.
+ *
+ * Why this exists (issue #204):
+ * gh-pages@6.3.0's "Removing files" step calls globby without `dot: true`, so
+ * dotfiles (.gitignore, .gitmodules, .github/…) and submodule gitlinks from the
+ * gh-pages branch are NOT removed before our dist is copied on top. They then
+ * get re-committed and leak into the deploy.
+ *
+ * Fix: after gh-pages' broken remove + our file copy, ask git what it still has
+ * indexed (`git ls-files -z`), diff against the set of files in our dist, and
+ * `git rm` the leftovers. `git rm` correctly handles submodule gitlinks too.
+ *
+ * Upstream fix: tschaub/gh-pages#612 (merged 2025-08-09, unreleased as of
+ * gh-pages@6.3.0). When a release containing that PR lands, this hook becomes
+ * redundant and can be removed.
+ */
+export function createCleanupBeforeAddHook(
+  distDir: string,
+  dotfiles: boolean,
+  logger: logging.LoggerApi
+): (git: GhPagesGit) => Promise<void> {
+  return async (git) => {
+    const distFiles = await collectDistFiles(distDir, dotfiles);
+    await git.exec('ls-files', '-z');
+    const tracked = (git.output || '').split('\0').filter(Boolean);
+    const toRemove = tracked.filter((f) => !distFiles.has(f));
+    if (toRemove.length === 0) {
+      return;
+    }
+    logger.info(
+      `Removing ${toRemove.length} leftover file(s) from gh-pages branch not in dist: ${toRemove.join(', ')}`
+    );
+    await git.rm(toRemove);
+  };
+}
+
 /**
  * Get the remote URL from the git repository
  *

src/engine/engine.ts

@@ -13,7 +13,8 @@ import {
   handleUserCredentials,
   warnDeprecatedParameters,
   appendCIMetadata,
-  injectTokenIntoRepoUrl
+  injectTokenIntoRepoUrl,
+  createCleanupBeforeAddHook
 } from './engine.prepare-options-helpers';
 
 export async function run(
@@ -194,7 +195,11 @@ async function publishViaGhPages(
     dotfiles: options.dotfiles,
     user: options.user,
     cname: options.cname,
-    nojekyll: options.nojekyll
+    nojekyll: options.nojekyll,
+    // Workaround for gh-pages#612 (unreleased in v6.3.0): clean up leftover
+    // gh-pages branch files (dotfiles, submodule gitlinks) that the broken
+    // remove step misses. Skipped when the user opts into additive mode.
+    beforeAdd: options.add ? undefined : createCleanupBeforeAddHook(dir, options.dotfiles, logger)
   };
 
   // gh-pages@6 silently absorbs errors via its internal .then(_, onRejected)

src/interfaces.ts

@@ -65,6 +65,7 @@ export interface PublishOptions {
   cname?: string;
   add?: boolean;
   git?: string;
+  beforeAdd?: (git: unknown) => void | Promise<void>;
   [key: string]: unknown; // Allow additional gh-pages options
 }
 

src/package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "angular-cli-ghpages",
-  "version": "3.0.3",
+  "version": "3.0.4",
   "description": "Deploy your Angular app to GitHub Pages or Cloudflare Pages directly from the Angular CLI (ng deploy)",
   "main": "index.js",
   "types": "index.d.ts",