0
# Jest Changed Files
1

2
Jest Changed Files is a utility module used internally by Jest to check which files have changed since the last commit in git, mercurial (hg), or sapling (sl) repositories. It provides file change detection functionality to enable Jest's ability to run tests only for changed code, significantly improving test performance in large codebases.
3

4
## Package Information
5

6
- **Package Name**: jest-changed-files
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install jest-changed-files`
10

11
## Core Imports
12

13
```typescript
14
import { getChangedFilesForRoots, findRepos } from "jest-changed-files";
15
import type { ChangedFiles, ChangedFilesPromise } from "jest-changed-files";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { getChangedFilesForRoots, findRepos } = require("jest-changed-files");
22
```
23

24
## Basic Usage
25

26
```typescript
27
import { getChangedFilesForRoots } from "jest-changed-files";
28

29
// Get changed files since last commit
30
const result = await getChangedFilesForRoots(["/path/to/project"], {
31
  lastCommit: true,
32
  withAncestor: false,
33
});
34

35
console.log(result.changedFiles); // Set of changed file paths
36
console.log(result.repos.git);    // Set of git repository paths
37
```
38

39
## Capabilities
40

41
### File Change Detection
42

43
Analyzes version control repositories to identify changed files based on various criteria. Supports git, mercurial (hg), and sapling (sl) repositories with configurable commit range detection.
44

45
```typescript { .api }
46
/**
47
 * Get the list of files and repos that have changed since the last commit or specified reference
48
 * @param roots - Array of string paths (typically Jest roots configuration)
49
 * @param options - Configuration options for change detection
50
 * @returns Promise resolving to object with changedFiles and repos information
51
 */
52
function getChangedFilesForRoots(
53
  roots: Array<string>, 
54
  options: {
55
    /** Check only the last commit for changes */
56
    lastCommit?: boolean;
57
    /** Include ancestor commit in comparison (uses HEAD^ for git) */
58
    withAncestor?: boolean;
59
    /** Compare changes since specified commit, branch, or tag */
60
    changedSince?: string;
61
  }
62
): Promise<ChangedFiles>;
63
```
64

65
**Usage Examples:**
66

67
```typescript
68
import { getChangedFilesForRoots } from "jest-changed-files";
69

70
// Check changes since last commit
71
const lastCommitChanges = await getChangedFilesForRoots(["/path/to/test"], {
72
  lastCommit: true,
73
  withAncestor: false,
74
});
75

76
// Check changes since specific branch/commit
77
const branchChanges = await getChangedFilesForRoots(["/path/to/test"], {
78
  changedSince: "main",
79
});
80

81
// Check changes with ancestor comparison
82
const ancestorChanges = await getChangedFilesForRoots(["/path/to/test"], {
83
  withAncestor: true,
84
});
85
```
86

87
### Repository Discovery
88

89
Discovers version control repositories (git, mercurial, sapling) within specified root directories using concurrent scanning with resource limiting.
90

91
```typescript { .api }
92
/**
93
 * Discover git, hg, and sapling repositories within specified root directories
94
 * @param roots - Array of directory paths to search for repositories
95
 * @returns Promise resolving to object containing Sets of repository paths by VCS type
96
 */
97
function findRepos(roots: Array<string>): Promise<{
98
  /** Set of git repository paths */
99
  git: Set<string>;
100
  /** Set of mercurial repository paths */
101
  hg: Set<string>;
102
  /** Set of sapling repository paths */
103
  sl: Set<string>;
104
}>;
105
```
106

107
**Usage Example:**
108

109
```typescript
110
import { findRepos } from "jest-changed-files";
111

112
const repos = await findRepos(["/path/to/search", "/another/path"]);
113

114
console.log(repos.git); // Set<string> of git repository paths
115
console.log(repos.hg);  // Set<string> of mercurial repository paths  
116
console.log(repos.sl);  // Set<string> of sapling repository paths
117
```
118

119
## Types
120

121
```typescript { .api }
122
interface ChangedFiles {
123
  /** Repository information organized by VCS type */
124
  repos: {
125
    /** Set of git repository paths */
126
    git: Set<string>;
127
    /** Set of mercurial repository paths */
128
    hg: Set<string>;
129
    /** Set of sapling repository paths */
130
    sl: Set<string>;
131
  };
132
  /** Set of absolute file paths that have changed */
133
  changedFiles: Set<string>;
134
}
135

136
type ChangedFilesPromise = Promise<ChangedFiles>;
137
```
138

139
## Implementation Notes
140

141
- **Concurrency Control**: Uses p-limit with a maximum of 5 concurrent operations to prevent resource exhaustion when scanning many directories
142
- **Multiple VCS Support**: Handles git, mercurial (hg), and sapling (sl) repositories with appropriate command-line interfaces
143
- **Path Resolution**: All returned file paths are resolved to absolute paths for consistency
144
- **Resource Management**: Implements mutex pattern to safely handle concurrent repository discovery across multiple root directories
145
- **Jest Integration**: Designed specifically for Jest's changed file detection but can be used as a standalone utility