filter-repo: clarify interactions between path filtering and path renaming

Signed-off-by: Elijah Newren <newren@gmail.com>

Documentation/git-filter-repo.txt

@@ -112,6 +112,10 @@ Filtering based on paths (see also --filename-callback)
 Renaming based on paths (see also --filename-callback)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+Note: if you combine path filtering with path renaming, be aware that
+      a rename directive does not select paths, it only says how to
+      rename paths that are selected with the filters.
+
 --path-rename <old_name:new_name>::
 --path-rename-match <old_name:new_name>::
 	Path to rename; if filename or directory matches <old_name>
@@ -616,6 +620,21 @@ created by the rename so reversing the two would give you an empty repo).
 Also, note that the rename of cmds/run_release.sh a couple examples ago was
 done before the other renames.
 
+Note that path renaming does not do path filtering, thus the following
+command
+
+--------------------------------------------------
+git filter-repo --path src/main/ --path-rename tools/:scripts/
+--------------------------------------------------
+
+would not result in the tools or scripts directories being present, because
+the single filter selected only src/main/.  It's likely that you would
+instead want to run:
+
+--------------------------------------------------
+git filter-repo --path src/main/ --path tools/ --path-rename tools/:scripts/
+--------------------------------------------------
+
 If you prefer to filter based solely on basename, use the `--use-base-name`
 flag (though this is incompatible with `--path-rename`).  For example, to
 only include README.md and Makefile files from any directory:

git-filter-repo

@@ -1792,7 +1792,9 @@ EXAMPLES
         action=FilteringOptions.AppendFilter,
         help=_("Path to rename; if filename or directory matches OLD_NAME "
                "rename to NEW_NAME.  Multiple --path-rename options can be "
-               "specified."))
+               "specified.  NOTE: If you combine filtering options with "
+               "renaming ones, do not rely on a rename argument to select "
+               "paths; you also need a filter to select them."))
 
     helpers = parser.add_argument_group(title=_("Path shortcuts"))
     helpers.add_argument('--paths-from-file', metavar='FILENAME',

t/t9390-filter-repo.sh

@@ -178,6 +178,85 @@ test_expect_success '--paths-from-file' '
 	)
 '
 
+create_path_filtering_and_renaming() {
+	test -d path_filtering_and_renaming && return
+
+	test_create_repo path_filtering_and_renaming &&
+	(
+		cd path_filtering_and_renaming &&
+
+		>.gitignore &&
+		mkdir -p src/main/java/com/org/{foo,bar} &&
+		mkdir -p src/main/resources &&
+		test_seq  1 10 >src/main/java/com/org/foo/uptoten &&
+		test_seq 11 20 >src/main/java/com/org/bar/uptotwenty &&
+		test_seq  1  7 >src/main/java/com/org/uptoseven &&
+		test_seq  1  5 >src/main/resources/uptofive &&
+		git add . &&
+		git commit -m Initial
+	)
+}
+
+test_expect_success 'Mixing filtering and renaming paths, not enough filters' '
+	create_path_filtering_and_renaming &&
+	git clone --no-local path_filtering_and_renaming \
+			     path_filtering_and_renaming_1 &&
+	(
+		cd path_filtering_and_renaming_1 &&
+
+		git filter-repo --path .gitignore \
+				--path src/main/resources \
+				--path-rename src/main/java/com/org/foo/:src/main/java/com/org/ &&
+
+		cat <<-EOF >expect &&
+		.gitignore
+		src/main/resources/uptofive
+		EOF
+		git ls-files >actual &&
+		test_cmp expect actual
+	)
+'
+
+test_expect_success 'Mixing filtering and renaming paths, enough filters' '
+	create_path_filtering_and_renaming &&
+	git clone --no-local path_filtering_and_renaming \
+			     path_filtering_and_renaming_2 &&
+	(
+		cd path_filtering_and_renaming_2 &&
+
+		git filter-repo --path .gitignore \
+				--path src/main/resources \
+				--path src/main/java/com/org/foo/ \
+				--path-rename src/main/java/com/org/foo/:src/main/java/com/org/ &&
+
+		cat <<-EOF >expect &&
+		.gitignore
+		src/main/java/com/org/uptoten
+		src/main/resources/uptofive
+		EOF
+		git ls-files >actual &&
+		test_cmp expect actual
+	)
+'
+
+test_expect_success 'Mixing filtering and to-subdirectory-filter' '
+	create_path_filtering_and_renaming &&
+	git clone --no-local path_filtering_and_renaming \
+			     path_filtering_and_renaming_3 &&
+	(
+		cd path_filtering_and_renaming_3 &&
+
+		git filter-repo --path src/main/resources \
+				--to-subdirectory-filter my-module &&
+
+		cat <<-EOF >expect &&
+		my-module/src/main/resources/uptofive
+		EOF
+		git ls-files >actual &&
+		test_cmp expect actual
+	)
+'
+
 test_expect_success 'setup metasyntactic repo' '
 	test_create_repo metasyntactic &&
 	(