git-apply --directory: make --root more similar to GNU diff

Applying a patch in the directory that is different from what the patch
records is done with --directory option in GNU diff.  The --root option we
introduced previously does the same, and we can call it the same way to
give users more familiar feel.

Signed-off-by: Junio C Hamano <gitster@pobox.com>

Documentation/git-apply.txt

@@ -14,7 +14,7 @@ SYNOPSIS
 	  [--allow-binary-replacement | --binary] [--reject] [-z]
 	  [-pNUM] [-CNUM] [--inaccurate-eof] [--cached]
 	  [--whitespace=<nowarn|warn|fix|error|error-all>]
-	  [--exclude=PATH] [--root=<root>] [--verbose] [<patch>...]
+	  [--exclude=PATH] [--directory=<root>] [--verbose] [<patch>...]
 
 DESCRIPTION
 -----------
@@ -177,9 +177,13 @@ behavior:
 	current patch being applied will be printed. This option will cause
 	additional information to be reported.
 
---root=<root>::
+--directory=<root>::
 	Prepend <root> to all filenames.  If a "-p" argument was passed, too,
 	it is applied before prepending the new root.
++
+For example, a patch that talks about updating `a/git-gui.sh` to `b/git-gui.sh`
+can be applied to the file in the working tree `modules/git-gui/git-gui.sh` by
+running `git apply --directory=modules/git-gui`.
 
 Configuration
 -------------

builtin-apply.c

@@ -3130,8 +3130,8 @@ int cmd_apply(int argc, const char **argv, const char *unused_prefix)
 			inaccurate_eof = 1;
 			continue;
 		}
-		if (!prefixcmp(arg, "--root=")) {
-			arg += strlen("--root=");
+		if (!prefixcmp(arg, "--directory=")) {
+			arg += strlen("--directory=");
 			root_len = strlen(arg);
 			if (root_len && arg[root_len - 1] != '/') {
 				char *new_root;

t/t4128-apply-root.sh

@@ -23,18 +23,18 @@ diff a/bla/blub/dir/file b/bla/blub/dir/file
 +Bello
 EOF
 
-test_expect_success 'apply --root -p (1)' '
+test_expect_success 'apply --directory -p (1)' '
 
-	git apply --root=some/sub -p3 --index patch &&
+	git apply --directory=some/sub -p3 --index patch &&
 	test Bello = $(git show :some/sub/dir/file) &&
 	test Bello = $(cat some/sub/dir/file)
 
 '
 
-test_expect_success 'apply --root -p (2) ' '
+test_expect_success 'apply --directory -p (2) ' '
 
 	git reset --hard initial &&
-	git apply --root=some/sub/ -p3 --index patch &&
+	git apply --directory=some/sub/ -p3 --index patch &&
 	test Bello = $(git show :some/sub/dir/file) &&
 	test Bello = $(cat some/sub/dir/file)