Skip to content

Commit 12335f4

Browse files
gliviugliviu
committed
Update readme
1 parent cf0e345 commit 12335f4

1 file changed

Lines changed: 68 additions & 62 deletions

File tree

‎README.md‎

Lines changed: 68 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -17,10 +17,10 @@ Node JS directory compare
1717
- [Extension points](#extension-points)
1818
* [File content comparators](#file-content-comparators)
1919
+ [Ignore line endings and white spaces](#ignore-line-endings-and-white-spaces)
20-
* [Name comparators](#name-comparators)
21-
* [Result builder](#result-builder)
2220
* [Glob filter](#glob-filter)
2321
+ [Implement .gitignore filter](#implement-gitignore-filter)
22+
* [Name comparators](#name-comparators)
23+
* [Result builder](#result-builder)
2424
- [UI tools](#ui-tools)
2525
- [Changelog](#changelog)
2626

@@ -83,8 +83,8 @@ compare(path1: string, path2: string, options?: Options): Promise<Result>
8383
compareSync(path1: string, path2: string, options?: Options): Result
8484
```
8585
More details can be found in the reference documentation:
86-
* [compare](https://gliviu.github.io/dc-api/index.html#compare)
87-
* [compareSync](https://gliviu.github.io/dc-api/index.html#compareSync)
86+
* [compare](https://gliviu.github.io/dc-api/functions/compare.html)
87+
* [compareSync](https://gliviu.github.io/dc-api/functions/compareSync.html)
8888
* [Options](https://gliviu.github.io/dc-api/interfaces/Options.html)
8989
* [Result](https://gliviu.github.io/dc-api/interfaces/Result.html)
9090

@@ -155,7 +155,7 @@ A couple of handlers are included in the library:
155155
* text sync compare - `dircompare.fileCompareHandlers.lineBasedFileCompare.compareSync`
156156
* text async compare - `dircompare.fileCompareHandlers.lineBasedFileCompare.compareAsync`
157157

158-
Use [defaultFileCompare.js](https://github.com/gliviu/dir-compare/blob/master/src/FileCompareHandler/default/defaultFileCompare.ts) as an example to create your own.
158+
Use [defaultFileCompare](https://github.com/gliviu/dir-compare/blob/master/src/FileCompareHandler/default/defaultFileCompare.ts) as an example to create your own.
159159

160160
### Ignore line endings and white spaces
161161
Line based comparator can be used to ignore line ending and white space differences.
@@ -180,6 +180,62 @@ console.log(res)
180180
dircompare.compare(path1, path2, options)
181181
.then(res => console.log(res))
182182
```
183+
184+
## Glob filter
185+
The current implementation of the glob filter uses minimatch and is based on [includeFilter and excludeFilter options](#glob-patterns). While it is meant to fit most use cases, [some scenarios](https://github.com/gliviu/dir-compare/issues/67) are not addressed.
186+
187+
Use [filterHandler option](https://gliviu.github.io/dc-api/interfaces/Options.html#filterHandler) to alter this behavior.
188+
189+
The following example demonstrates how to include only files with a specific extension in our comparison.
190+
```typescript
191+
import { Options, compareSync, Result, FilterHandler, Entry, filterHandlers } from 'dir-compare'
192+
import { extname } from 'path'
193+
194+
var d1 = '...';
195+
var d2 = '...';
196+
197+
const filterByfileExtension: FilterHandler = (entry: Entry, relativePath: string, options: Options): boolean => {
198+
if (!options.fileExtension) {
199+
// Fallback on the default 'minimatch' implementation
200+
return filterHandlers.defaultFilterHandler(entry, relativePath, options)
201+
}
202+
203+
return options.fileExtension === extname(entry.name)
204+
}
205+
206+
const options: Options = {
207+
compareSize: true,
208+
fileExtension: '.txt',
209+
filterHandler: filterByfileExtension
210+
}
211+
212+
const res: Result = compareSync(d1, d2, options)
213+
```
214+
215+
For reference, the default minimatch filter can be found in [defaultFilterHandler](https://github.com/gliviu/dir-compare/blob/master/src/FilterHandler/defaultFilterHandler.ts) which is exposed by [filterHandlers property](https://gliviu.github.io/dc-api/variables/filterHandlers.html).
216+
217+
### Implement .gitignore filter
218+
[Globby](https://www.npmjs.com/package/globby) library provides the functionality to parse and apply `.gitignore` rules.
219+
This is a [sample implementation](https://github.com/gliviu/dir-compare/blob/master/test/extended/gitignoreSupport/gitignoreFilter.ts) that uses globby and dir-compare filter extension.
220+
221+
Usage:
222+
```typescript
223+
import { Options, compareSync, Result} from 'dir-compare'
224+
import { getGitignoreFilter } from './gitignoreFilter.js'
225+
226+
var d1 = '...';
227+
var d2 = '...';
228+
229+
const options: Options = {
230+
compareSize: true,
231+
filterHandler: getGitignoreFilter(d1, d2),
232+
includeFilter: '*.js' // if present, regular filters are applied after .gitignore rules.
233+
}
234+
235+
const res: Result = compareSync(d1, d2, options)
236+
237+
```
238+
183239
## Name comparators
184240
If [default](https://github.com/gliviu/dir-compare/blob/master/src/NameCompare/defaultNameCompare.ts) name comparison is not enough, custom behavior can be specified with [compareNameHandler](https://gliviu.github.io/dc-api/interfaces/Options.html#compareNameHandler) option.
185241
Following example adds the possibility to ignore file extensions.
@@ -221,6 +277,8 @@ const res = compare(path1, path2, options).then(res => {
221277
// icon.svg icon.png equal
222278
// logo.svg logo.jpg equal
223279
```
280+
For reference, the default name comparator can be found in [defaultNameCompare](https://github.com/gliviu/dir-compare/blob/master/src/NameCompare/defaultNameCompare.ts) which is exposed by [compareNameHandlers property](https://gliviu.github.io/dc-api/variables/compareNameHandlers.html).
281+
224282

225283
## Result builder
226284
[Result builder](https://gliviu.github.io/dc-api/interfaces/Options.html#resultBuilder) is called for each pair of entries encountered during comparison. Its purpose is to append entries in `diffSet` and eventually update `statistics` object with new stats.
@@ -244,74 +302,22 @@ const res = dircompare.compareSync('...', '...', options)
244302

245303
The [default](https://github.com/gliviu/dir-compare/blob/master/src/ResultBuilder/defaultResultBuilderCallback.ts) builder can be used as an example.
246304

247-
## Glob filter
248-
The current implementation of the glob filter uses minimatch and is based on [includeFilter and excludeFilter options](#glob-patterns). While it is meant to fit most use cases, [some scenarios](https://github.com/gliviu/dir-compare/issues/67) are not addressed.
249-
250-
Use [filterHandler option](https://gliviu.github.io/dc-api/interfaces/Options.html#filterHandler) to alter this behavior.
251-
252-
The following example demonstrates how to include only files with a specific extension in our comparison.
253-
```typescript
254-
import { Options, compareSync, Result, FilterHandler, Entry, filterHandlers } from './'
255-
import { extname } from 'path'
256-
257-
var d1 = '...';
258-
var d2 = '...';
259-
260-
const filterByfileExtension: FilterHandler = (entry: Entry, relativePath: string, options: Options): boolean => {
261-
if (!options.fileExtension) {
262-
// Fallback on the default 'minimatch' implementation
263-
return filterHandlers.defaultFilterHandler(entry, relativePath, options)
264-
}
265-
266-
return options.fileExtension === extname(entry.name)
267-
}
268-
269-
const options: Options = {
270-
compareSize: true,
271-
fileExtension: '.txt',
272-
filterHandler: filterByfileExtension
273-
}
274-
275-
const res: Result = compareSync(d1, d2, options)
276-
```
277-
278-
For reference, the default minimatch filter can be found in [defaultFilterHandler](https://github.com/gliviu/dir-compare/blob/master/src/FilterHandler/defaultFilterHandler.ts) which is exposed by [filterHandlers property](https://gliviu.github.io/dc-api/index.html#filterHandlers).
279-
280-
### Implement .gitignore filter
281-
[Globby](https://github.com/sindresorhus/globby) library provides the functionality to parse and apply `.gitignore` rules.
282-
This is a [sample implementation](https://github.com/gliviu/dir-compare/blob/master/test/extended/gitignoreSupport/gitignoreFilter.ts) that uses globby and dir-compare filter extension.
283-
284-
Usage:
285-
```typescript
286-
import { Options, compareSync, Result} from 'dir-compare'
287-
import { getGitignoreFilter } from './gitignoreFilter.js'
288-
289-
var d1 = '...';
290-
var d2 = '...';
291-
292-
const options: Options = {
293-
compareSize: true,
294-
filterHandler: getGitignoreFilter(d1, d2),
295-
includeFilter: '*.js' // if present, regular filters are applied after .gitignore rules.
296-
}
297-
298-
const res: Result = compareSync(d1, d2, options)
299-
300-
```
301-
302305
# UI tools
303306
* [dir-compare-cli](https://github.com/gliviu/dir-compare-cli)
304307
* [Visual Studio Code - Compare Folders](https://marketplace.visualstudio.com/items?itemName=moshfeu.compare-folders)
305308

306309
# Changelog
310+
* v4.2.0
311+
* Updated dependencies
312+
* Increased test coverage
307313
* v4.1.0
308314
* Possibility to alter the default [Glob filter](#glob-filter) behavior
309315
* [Ignore files and directories according to .gitignore rules](#implement-gitignore-filter).
310316
* New [origin](https://gliviu.github.io/dc-api/interfaces/Entry.html#origin) field in Entry to distinguish between the left or right directory
311317
* Improved api documentation
312318
* v4.0.0
313319
* Switched project to typescript
314-
* [Async comparator](https://gliviu.github.io/dc-api/index.html#compare) improvements when comparing large directory structures
320+
* [Async comparator](https://gliviu.github.io/dc-api/functions/compare.html) improvements when comparing large directory structures
315321
* Heap usage has decreased 3x compared to previous version
316322
* Works 2x faster when comparing by content
317323
* Better concurrency. UI apps will be more responsive while comparison is ongoing
@@ -331,7 +337,7 @@ const res: Result = compareSync(d1, d2, options)
331337
* New field indicating reason for two entries being distinct.
332338
* Improved command line output format.
333339
* Tests are no longer part of published package.
334-
* Generated [Api](https://gliviu.github.io/dc-api/index.html) documentation.
340+
* Generated [Api](https://gliviu.github.io/dc-api) documentation.
335341

336342
Breaking changes:
337343
* Broken links are no longer treated as errors. As a result there are new statistics (leftBrokenLinks, rightBrokenLinks, distinctBrokenLinks, totalBrokenLinks) and new entry type - broken-link.

0 commit comments

Comments
 (0)