feat: add .actorignore support (#1038)

Co-authored-by: Vlad Frangu <me@vladfrangu.dev>

Author: l2ysho

src/commands/actors/push.ts

@@ -48,6 +48,8 @@ export class ActorsPushCommand extends ApifyCommand<typeof ActorsPushCommand> {
 		`Deploys Actor to Apify platform using settings from '${LOCAL_CONFIG_PATH}'.\n` +
 		`Files under '${MAX_MULTIFILE_BYTES / 1024 ** 2}' MB upload as "Multiple source files"; ` +
 		`larger projects upload as ZIP file.\n` +
+		`Files matched by .gitignore and .actorignore are excluded. ` +
+		`Use negation patterns (e.g. !dist/) in .actorignore to force-include git-ignored files.\n` +
 		`Use --force to override newer remote versions.`;
 
 	static override enableJsonFlag = true;

src/lib/utils.ts

@@ -22,7 +22,7 @@ import { Mime } from 'mime';
 import otherMimes from 'mime/types/other.js';
 import standardMimes from 'mime/types/standard.js';
 import { gte, minVersion, satisfies } from 'semver';
-import { escapePath, glob } from 'tinyglobby';
+import { glob } from 'tinyglobby';
 
 import {
 	ACTOR_ENV_VARS,
@@ -50,6 +50,10 @@ import { deleteFile, ensureFolderExistsSync, rimrafPromised } from './files.js';
 import type { AuthJSON } from './types.js';
 import { cliDebugPrint } from './utils/cliDebugPrint.js';
 
+// `ignore` is a CJS package; TypeScript sees its default import as the module
+// object rather than the callable factory, so we cast through unknown.
+const makeIg = ignoreModule as unknown as () => Ignore;
+
 // Export AJV properly: https://github.com/ajv-validator/ajv/issues/2132
 // Welcome to the state of JavaScript/TypeScript and CJS/ESM interop.
 export const Ajv2019 = _Ajv2019 as unknown as typeof import('ajv/dist/2019.js').default;
@@ -306,10 +310,6 @@ const getGitignoreFallbackFilter = async (cwd: string): Promise<(paths: string[]
 		expandDirectories: false,
 	});
 
-	// `ignore` is a CJS package; TypeScript sees its default import as the module
-	// object rather than the callable factory, so we cast through unknown.
-	const makeIg = ignoreModule as unknown as () => Ignore;
-
 	const filters: { dir: string; ig: Ignore; ancestorPrefix?: string }[] = [];
 
 	for (const gitignoreFile of gitignoreFiles) {
@@ -368,16 +368,59 @@ const getGitignoreFallbackFilter = async (cwd: string): Promise<(paths: string[]
 		});
 };
 
+interface ActorIgnoreResult {
+	/** Filter that removes paths matching non-negated .actorignore patterns */
+	excludeFilter: ((paths: string[]) => string[]) | null;
+	/** Patterns from negation lines (with `!` stripped) — files matching these should be force-included even if git-ignored */
+	forceIncludePatterns: string[];
+}
+
+const parseActorIgnore = async (cwd: string): Promise<ActorIgnoreResult> => {
+	const actorignorePath = join(cwd, '.actorignore');
+	if (!existsSync(actorignorePath)) {
+		return { excludeFilter: null, forceIncludePatterns: [] };
+	}
+
+	const content = await readFile(actorignorePath, 'utf-8');
+	const lines = content.split('\n');
+
+	const excludeLines: string[] = [];
+	const forceIncludePatterns: string[] = [];
+
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (!trimmed || trimmed.startsWith('#')) continue;
+		if (trimmed.startsWith('!')) {
+			forceIncludePatterns.push(trimmed.slice(1));
+		} else {
+			excludeLines.push(trimmed);
+		}
+	}
+
+	const excludeFilter =
+		excludeLines.length > 0
+			? (paths: string[]) => {
+					const ig = makeIg().add(excludeLines);
+					return paths.filter((filePath) => !ig.ignores(filePath));
+				}
+			: null;
+
+	return { excludeFilter, forceIncludePatterns };
+};
+
 /**
- * Get Actor local files, omit files defined in .gitignore and .git folder
+ * Get Actor local files, omit files defined in .gitignore, .actorignore and .git folder
  * All dot files(.file) and folders(.folder/) are included.
  */
 export const getActorLocalFilePaths = async (cwd?: string) => {
 	const resolvedCwd = cwd ?? process.cwd();
 
-	const ignore = ['.git/**', 'apify_storage', 'node_modules', 'storage', 'crawlee_storage'];
+	const hardcodedIgnore = ['.git/**', 'apify_storage', 'node_modules', 'storage', 'crawlee_storage'];
 
-	let fallbackFilter: ((paths: string[]) => string[]) | null = null;
+	// Parse .actorignore early to get both exclude filter and force-include patterns
+	const { excludeFilter: actorignoreFilter, forceIncludePatterns } = await parseActorIgnore(resolvedCwd);
+
+	let gitIgnoreFilter: ((paths: string[]) => string[]) | null = null;
 
 	// Use git ls-files to get gitignored paths — this correctly handles ancestor .gitignore files,
 	// nested .gitignore files, .git/info/exclude, and global gitignore config
@@ -388,23 +431,53 @@ export const getActorLocalFilePaths = async (cwd?: string) => {
 			stdio: ['ignore', 'pipe', 'ignore'],
 		})
 			.split('\n')
-			.filter(Boolean)
-			.map((p) => escapePath(p));
+			.filter(Boolean);
 
-		ignore.push(...gitIgnored);
+		if (gitIgnored.length > 0) {
+			const ig = makeIg().add(gitIgnored);
+			gitIgnoreFilter = (paths) => paths.filter((p) => !ig.ignores(p));
+		}
 	} catch {
 		// git is unavailable or directory is not a git repo — fall back to parsing .gitignore files
-		fallbackFilter = await getGitignoreFallbackFilter(resolvedCwd);
+		gitIgnoreFilter = await getGitignoreFallbackFilter(resolvedCwd);
 	}
 
-	const paths = await glob(['*', '**/**'], {
-		ignore,
+	const allFiles = await glob(['*', '**/**'], {
+		ignore: hardcodedIgnore,
 		dot: true,
 		expandDirectories: false,
 		cwd: resolvedCwd,
 	});
 
-	return fallbackFilter ? fallbackFilter(paths) : paths;
+	let paths = gitIgnoreFilter ? gitIgnoreFilter(allFiles) : allFiles;
+
+	if (actorignoreFilter) {
+		paths = actorignoreFilter(paths);
+	}
+
+	// Force-include: negation patterns in .actorignore (e.g. !dist/) override gitignore,
+	// allowing git-ignored files to be included in the push
+	if (forceIncludePatterns.length > 0) {
+		const forceIncludeIg = makeIg().add(forceIncludePatterns);
+		const forceIncluded = allFiles.filter((filePath) => forceIncludeIg.ignores(filePath));
+		const pathSet = new Set(paths);
+		for (const file of forceIncluded) {
+			pathSet.add(file);
+		}
+		paths = [...pathSet];
+	}
+
+	// .actor/ is the Actor specification folder — always include it regardless of gitignore/actorignore
+	const actorSpecFiles = allFiles.filter((p) => p === '.actor' || p.startsWith('.actor/'));
+	if (actorSpecFiles.length > 0) {
+		const pathSet = new Set(paths);
+		for (const file of actorSpecFiles) {
+			pathSet.add(file);
+		}
+		paths = [...pathSet];
+	}
+
+	return paths;
 };
 
 /**

test/local/lib/utils-actorignore-no-git.test.ts

@@ -0,0 +1,100 @@
+import { writeFileSync } from 'node:fs';
+
+import { ensureFolderExistsSync } from '../../../src/lib/files.js';
+import { getActorLocalFilePaths } from '../../../src/lib/utils.js';
+import { useTempPath } from '../../__setup__/hooks/useTempPath.js';
+
+// Mock execSync to simulate git not being available.
+vi.mock('node:child_process', async (importOriginal) => {
+	const original = await importOriginal<typeof import('node:child_process')>();
+	return {
+		...original,
+		execSync: () => {
+			throw new Error('not a git repository');
+		},
+	};
+});
+
+const TEST_DIR = 'actorignore-no-git-test-dir';
+const FOLDERS = ['src', 'docs', 'dist'];
+const FILES = ['main.js', 'src/index.js'];
+const FILES_TO_GITIGNORE = ['dist/bundle.js'];
+const FILES_TO_ACTORIGNORE = ['docs/README.md'];
+
+describe('Utils - .actorignore with .gitignore fallback (no git)', () => {
+	const { tmpPath, joinPath, beforeAllCalls, afterAllCalls } = useTempPath(TEST_DIR, {
+		create: true,
+		remove: true,
+		cwd: false,
+		cwdParent: false,
+	});
+
+	beforeAll(async () => {
+		await beforeAllCalls();
+
+		FOLDERS.forEach((folder) => {
+			ensureFolderExistsSync(tmpPath, folder);
+		});
+
+		FILES.concat(FILES_TO_GITIGNORE, FILES_TO_ACTORIGNORE).forEach((file) =>
+			writeFileSync(joinPath(file), 'content', { flag: 'w' }),
+		);
+
+		writeFileSync(joinPath('.gitignore'), 'dist/\n', { flag: 'w' });
+		writeFileSync(joinPath('.actorignore'), 'docs/\n', { flag: 'w' });
+	});
+
+	afterAll(async () => {
+		await afterAllCalls();
+	});
+
+	it('should exclude files matched by both .gitignore and .actorignore', async () => {
+		const paths = await getActorLocalFilePaths(tmpPath);
+
+		FILES.forEach((file) => expect(paths).toContain(file));
+		FILES_TO_GITIGNORE.forEach((file) => expect(paths).not.toContain(file));
+		FILES_TO_ACTORIGNORE.forEach((file) => expect(paths).not.toContain(file));
+	});
+});
+
+const NEGATE_NO_GIT_TEST_DIR = 'actorignore-negate-no-git-test-dir';
+const NEGATE_FOLDERS = ['src', 'dist'];
+const NEGATE_FILES = ['main.js', 'src/index.js'];
+const NEGATE_FILES_TO_GITIGNORE = ['dist/bundle.js'];
+
+describe('Utils - .actorignore negation overrides gitignore (no git)', () => {
+	const { tmpPath, joinPath, beforeAllCalls, afterAllCalls } = useTempPath(NEGATE_NO_GIT_TEST_DIR, {
+		create: true,
+		remove: true,
+		cwd: false,
+		cwdParent: false,
+	});
+
+	beforeAll(async () => {
+		await beforeAllCalls();
+
+		NEGATE_FOLDERS.forEach((folder) => {
+			ensureFolderExistsSync(tmpPath, folder);
+		});
+
+		NEGATE_FILES.concat(NEGATE_FILES_TO_GITIGNORE).forEach((file) =>
+			writeFileSync(joinPath(file), 'content', { flag: 'w' }),
+		);
+
+		writeFileSync(joinPath('.gitignore'), 'dist/\n', { flag: 'w' });
+		// .actorignore force-includes dist/ (overrides gitignore)
+		writeFileSync(joinPath('.actorignore'), '!dist/\n', { flag: 'w' });
+	});
+
+	afterAll(async () => {
+		await afterAllCalls();
+	});
+
+	it('should include gitignored files that match negation patterns in .actorignore', async () => {
+		const paths = await getActorLocalFilePaths(tmpPath);
+
+		NEGATE_FILES.forEach((file) => expect(paths).toContain(file));
+		// dist/bundle.js is gitignored but force-included by .actorignore
+		NEGATE_FILES_TO_GITIGNORE.forEach((file) => expect(paths).toContain(file));
+	});
+});