{"thread":{"id":"60789","subject":"[PATCH] ls-files: avoid the verb \"deprecate\" for individual options","startedAt":"2024-01-24T21:10:37Z","lastAt":"2024-01-25T18:55:05Z","messageCount":3,"participants":["Junio C Hamano","Jeff King"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"487353","messageId":"xmqqjznybfp4.fsf@gitster.g","threadId":"60789","inReplyTo":null,"subject":"[PATCH] ls-files: avoid the verb \"deprecate\" for individual options","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-01-24T21:10:31Z","receivedAt":"2024-01-24T21:10:37Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"When e750951e (ls-files: guide folks to --exclude-standard over\nother --exclude* options, 2023-01-13) updated the documentation to\ngive greater visibility to the `--exclude-standard` option, it marked\nthe `--exclude-per-directory` option as \"deprecated\".\n\nWhile it is technically correct that being deprecated does not\nnecessarily mean it is planned to be removed later, it seems to\ncause confusion to readers, especially when we merely mean\n\n The option Y can be used to achieve the same thing as the option\n X much simpler. To those of you who aren't familiar with either\n X or Y, we would recommend to use Y when appropriate.\n\nThis is especially true for `--exclude-standard` vs the combination\nof more granular `--exclude-from` and `--exclude-per-directory`\noptions. It is true that one common combination of the granular\noptions can be obtained by just giving the former, but that does not\nnecessarily mean a more granular control is not necessary.\n\nState the reason why we recommend readers `--exclude-standard` in\nthe description of `--exclude-per-directory`, instead of saying that\nthe option is deprecated. Also, spell out the recipe to emulate\nwhat `--exclude-standard` does, so that the users can give it minute\ntweaks (like \"do the same as Git Porcelain, except I do not want to\nread the global exclusion file from core.excludes\").\n\nSigned-off-by: Junio C Hamano \n---\n\n * With the grammofix by Peff squashed in and with minor tweaks to\n the proposed log message.\n\n Documentation/git-ls-files.txt | 23 ++++++++++++++++++-----\n 1 file changed, 18 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex f65a8cd91d..9447f2d8f4 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -119,8 +119,10 @@ OPTIONS\n \n --exclude-per-directory=::\n \tRead additional exclude patterns that apply only to the\n-\tdirectory and its subdirectories in . Deprecated; use\n-\t--exclude-standard instead.\n+\tdirectory and its subdirectories in . If you are\n+\ttrying to emulate the way Porcelain commands work, using\n+\tthe `--exclude-standard` instead is easier and more\n+\tthorough.\n \n --exclude-standard::\n \tAdd the standard Git exclusions: .git/info/exclude, .gitignore\n@@ -298,9 +300,8 @@ traversing the directory tree and finding files to show when the\n flags --others or --ignored are specified. linkgit:gitignore[5]\n specifies the format of exclude patterns.\n \n-Generally, you should just use --exclude-standard, but for historical\n-reasons the exclude patterns can be specified from the following\n-places, in order:\n+These exclude patterns can be specified from the following places,\n+in order:\n \n 1. The command-line flag --exclude= specifies a\n single pattern. Patterns are ordered in the same order\n@@ -322,6 +323,18 @@ top of the directory tree. A pattern read from a file specified\n by --exclude-per-directory is relative to the directory that the\n pattern file appears in.\n \n+Generally, you should be able to use `--exclude-standard` when you\n+want the exclude rules applied the same way as what Porcelain\n+commands do. To emulate what `--exclude-standard` specifies, you\n+can give `--exclude-per-directory=.gitignore`, and then specify:\n+\n+ 1. The file specified by the `core.excludesfile` configuration\n+ variable, if exists, or the `$XDG_CONFIG_HOME/git/ignore` file.\n+\n+ 2. The `$GIT_DIR/info/exclude` file.\n+\n+via the `--exclude-from=` option.\n+\n SEE ALSO\n --------\n linkgit:git-read-tree[1], linkgit:gitignore[5]\n-- \n2.43.0-386-ge02ecfcc53\n\n"},{"id":"487373","messageId":"20240125180625.GA54488@coredump.intra.peff.net","threadId":"60789","inReplyTo":"xmqqjznybfp4.fsf@gitster.g","subject":"Re: [PATCH] ls-files: avoid the verb \"deprecate\" for individual options","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2024-01-25T18:06:25Z","receivedAt":"2024-01-25T18:06:32Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Jan 24, 2024 at 01:10:31PM -0800, Junio C Hamano wrote:\n\n> --exclude-per-directory=::\n> \tRead additional exclude patterns that apply only to the\n> -\tdirectory and its subdirectories in . Deprecated; use\n> -\t--exclude-standard instead.\n> +\tdirectory and its subdirectories in . If you are\n> +\ttrying to emulate the way Porcelain commands work, using\n> +\tthe `--exclude-standard` instead is easier and more\n> +\tthorough.\n\nSorry I missed this gramm-o before, but should be \"the --exclude-standard\noption\" or just \"--exclude-standard\".\n\n-Peff\n"},{"id":"487377","messageId":"xmqqfrylw8e1.fsf@gitster.g","threadId":"60789","inReplyTo":"20240125180625.GA54488@coredump.intra.peff.net","subject":"Re: [PATCH] ls-files: avoid the verb \"deprecate\" for individual options","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-01-25T18:55:02Z","receivedAt":"2024-01-25T18:55:05Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> On Wed, Jan 24, 2024 at 01:10:31PM -0800, Junio C Hamano wrote:\n>\n>> --exclude-per-directory=::\n>> \tRead additional exclude patterns that apply only to the\n>> -\tdirectory and its subdirectories in . Deprecated; use\n>> -\t--exclude-standard instead.\n>> +\tdirectory and its subdirectories in . If you are\n>> +\ttrying to emulate the way Porcelain commands work, using\n>> +\tthe `--exclude-standard` instead is easier and more\n>> +\tthorough.\n>\n> Sorry I missed this gramm-o before, but should be \"the --exclude-standard\n> option\" or just \"--exclude-standard\".\n\nOops, certainly.\n"}]}