Skip to content

Docs: Clarify how reference and compared directories are processed #83

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Sep 8, 2025
Merged

Docs: Clarify how reference and compared directories are processed #83

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
dc97163
Docs: Clarify how reference and compared directories are processed
adrien-berchet Sep 8, 2025
30e508f
Docs: More
adrien-berchet Sep 8, 2025
8ae641f
Docs: Apply suggestions from code review
adrien-berchet Sep 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 13 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ the files, so it is not able to report which values are different.

### Compare two directories

If one wants to compare two directories with the following structures:
Let's compare two directories with the following structures:

```bash
└── reference_dir
Expand All @@ -55,6 +55,9 @@ If one wants to compare two directories with the following structures:
└── file_1.c
```

The `reference` directory contains all the files that should be checked in the `compared` directory,
which means that extraneous files in the `compared` directory are just ignored.

These two directories can be compared with the following code:

```python
Expand All @@ -63,7 +66,15 @@ import dir_content_diff
dir_content_diff.compare_trees("reference_dir", "compared_dir")
```

This code will return an empty dictionary because no difference was detected.
> [!WARNING]
> The order of the parameters is important: the first path is considered as the `reference`
> directory while the second one is the `compared` directory. Inverting the parameters may return
> a different result (in this example it would return that the file `sub_file_3.b` is missing).

If all the files are identical, this code will return an empty dictionary because no difference
was detected. As mentioned previously, this is because `dir-content-diff` is only looking for files
in the compared directory that are also present in the reference directory, so the file
`sub_file_3.b` is just ignored in this case.

If ``reference_dir/file_1.c`` is the following JSON-like file:

Expand Down