From dc97163b95cb35ea0b033b7862db2df4ded6ba16 Mon Sep 17 00:00:00 2001 From: Adrien Berchet Date: Mon, 8 Sep 2025 14:29:29 +0200 Subject: [PATCH 1/3] Docs: Clarify how reference and compared directories are processed --- README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 740eb3f..4ac27c6 100644 --- a/README.md +++ b/README.md @@ -63,7 +63,10 @@ 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. +If all the files are identical, this code will return an empty dictionary because no difference +was detected. This is because `dir-content-diff` is only looking for files in the compared directory +that are also present in the reference directory. Thus extraneous files from the compared directory +are not considered. If ``reference_dir/file_1.c`` is the following JSON-like file: From 30e508f1d123a52b6dc3380b619dac92045a4522 Mon Sep 17 00:00:00 2001 From: Adrien Berchet Date: Mon, 8 Sep 2025 14:49:09 +0200 Subject: [PATCH 2/3] Docs: More --- README.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 4ac27c6..7b83efe 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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 @@ -63,10 +66,15 @@ import dir_content_diff dir_content_diff.compare_trees("reference_dir", "compared_dir") ``` +> [!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 way 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. This is because `dir-content-diff` is only looking for files in the compared directory -that are also present in the reference directory. Thus extraneous files from the compared directory -are not considered. +was detected. As pointed 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: From 8ae641f40868a07e5373d909289df18b650c92da Mon Sep 17 00:00:00 2001 From: Adrien Berchet Date: Mon, 8 Sep 2025 14:51:29 +0200 Subject: [PATCH 3/3] Docs: Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7b83efe..cbf03bb 100644 --- a/README.md +++ b/README.md @@ -68,11 +68,11 @@ dir_content_diff.compare_trees("reference_dir", "compared_dir") > [!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 way return +> 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 pointed previously, this is because `dir-content-diff` is only looking for files +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.