undef/git-commit-vandalism
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
e86bbcf987
git-commit-vandalism/Documentation
History
Elijah Newren e86bbcf987 clean: disambiguate the definition of -d 
The -d flag pre-dated git-clean's ability to have paths specified.  As
such, the default for git-clean was to only remove untracked files in
the current directory, and -d existed to allow it to recurse into
subdirectories.

The interaction of paths and the -d option appears to not have been
carefully considered, as evidenced by numerous bugs and a dearth of
tests covering such pairings in the testsuite.  The definition turns out
to be important, so let's look at some of the various ways one could
interpret the -d option:

  A) Without -d, only look in subdirectories which contain tracked
     files under them; with -d, also look in subdirectories which
     are untracked for files to clean.

  B) Without specified paths from the user for us to delete, we need to
     have some kind of default, so...without -d, only look in
     subdirectories which contain tracked files under them; with -d,
     also look in subdirectories which are untracked for files to clean.

The important distinction here is that choice B says that the presence
or absence of '-d' is irrelevant if paths are specified.  The logic
behind option B is that if a user explicitly asked us to clean a
specified pathspec, then we should clean anything that matches that
pathspec.  Some examples may clarify.  Should

   git clean -f untracked_dir/file

remove untracked_dir/file or not?  It seems crazy not to, but a strict
reading of option A says it shouldn't be removed.  How about

   git clean -f untracked_dir/file1 tracked_dir/file2

or

   git clean -f untracked_dir_1/file1 untracked_dir_2/file2

?  Should it remove either or both of these files?  Should it require
multiple runs to remove both the files listed?  (If this sounds like a
crazy question to even ask, see the commit message of "t7300: Add some
testcases showing failure to clean specified pathspecs" added earlier in
this patch series.)  What if -ffd were used instead of -f -- should that
allow these to be removed?  Should it take multiple invocations with
-ffd?  What if a glob (such as '*tracked*') were used instead of
spelling out the directory names?  What if the filenames involved globs,
such as

   git clean -f '*.o'

or

   git clean -f '*/*.o'

?

The current documentation actually suggests a definition that is
slightly different than choice A, and the implementation prior to this
series provided something radically different than either choices A or
B. (The implementation, though, was clearly just buggy).  There may be
other choices as well.  However, for almost any given choice of
definition for -d that I can think of, some of the examples above will
appear buggy to the user.  The only case that doesn't have negative
surprises is choice B: treat a user-specified path as a request to clean
all untracked files which match that path specification, including
recursing into any untracked directories.

Change the documentation and basic implementation to use this
definition.

There were two regression tests that indirectly depended on the current
implementation, but neither was about subdirectory handling.  These two
tests were introduced in commit 5b7570cfb4 ("git-clean: add tests for
relative path", 2008-03-07) which was solely created to add coverage for
the changes in commit fb328947c8e ("git-clean: correct printing relative
path", 2008-03-07).  Both tests specified a directory that happened to
have an untracked subdirectory, but both were only checking that the
resulting printout of a file that was removed was shown with a relative
path.  Update these tests appropriately.

Signed-off-by: Elijah Newren <newren@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-09-17 12:20:35 -07:00
..
config Merge branch 'dl/config-alias-doc' into maint 2019-07-29 12:38:15 -07:00
howto doc: format pathnames and URLs as monospace. 2019-03-13 11:14:22 +09:00
RelNotes Git 2.22.1 2019-08-11 15:07:51 -07:00
technical Merge branch 'ds/close-object-store' into maint 2019-07-29 12:38:22 -07:00
.gitattributes
.gitignore Merge branch 'js/misc-doc-fixes' 2019-05-09 00:37:27 +09:00
asciidoc.conf
asciidoctor-extensions.rb asciidoctor-extensions: fix spurious space after linkgit 2019-03-11 18:22:07 +09:00
blame-options.txt
build-docdep.perl
cat-texi.perl
cmd-list.perl
CodingGuidelines Merge branch 'jc/post-c89-rules-doc' into maint 2019-07-29 12:38:23 -07:00
config.txt trace2: update docs to describe system/global config settings 2019-04-16 13:37:07 +09:00
date-formats.txt
diff-format.txt log,diff-tree: add --combined-all-paths option 2019-02-07 20:15:25 -08:00
diff-generate-patch.txt log,diff-tree: add --combined-all-paths option 2019-02-07 20:15:25 -08:00
diff-options.txt Merge branch 'nd/diff-parseopt-3' 2019-04-16 19:28:03 +09:00
doc-diff doc-diff: add --cut-header-footer 2019-03-18 15:54:17 +09:00
docbook-xsl.css
docbook.xsl
everyday.txto
fetch-options.txt clone: send server options when using protocol v2 2019-04-18 10:53:51 +09:00
fix-texi.perl
git-add.txt docs: move core.excludesFile from git-add to gitignore 2019-03-08 09:12:45 +09:00
git-am.txt am/cherry-pick/rebase/revert: document --rerere-autoupdate 2019-03-18 10:24:56 +09:00
git-annotate.txt Use proper syntax for replaceables in command docs 2018-05-25 17:16:47 +09:00
git-apply.txt Merge branch 'nd/diff-apply-ita' 2018-06-25 13:22:36 -07:00
git-archimport.txt git-archimport.1: specify what kind of Arch we're talking about 2018-09-21 09:28:58 -07:00
git-archive.txt
git-bisect-lk2009.txt doc: fix ASCII art tab spacing 2018-10-23 12:23:09 +09:00
git-bisect.txt Merge branch 'ak/bisect-doc-typofix' 2018-04-25 13:28:56 +09:00
git-blame.txt diff: --indent-heuristic is no longer experimental 2017-11-02 14:51:24 +09:00
git-branch.txt Merge branch 'po/doc-branch' into maint 2019-07-29 12:38:16 -07:00
git-bundle.txt doc: keep first level section header in upper case 2018-05-02 17:03:33 +09:00
git-cat-file.txt Merge branch 'dt/cat-file-batch-ambiguous' 2019-02-06 22:05:21 -08:00
git-check-attr.txt Use proper syntax for replaceables in command docs 2018-05-25 17:16:47 +09:00
git-check-ignore.txt Use proper syntax for replaceables in command docs 2018-05-25 17:16:47 +09:00
git-check-mailmap.txt Use proper syntax for replaceables in command docs 2018-05-25 17:16:47 +09:00
git-check-ref-format.txt Doc/check-ref-format: clarify information about @{-N} syntax 2017-12-19 10:00:45 -08:00
git-checkout-index.txt
git-checkout.txt Merge branch 'dl/branch-from-3dot-merge-base' 2019-05-19 16:45:28 +09:00
git-cherry-pick.txt cherry-pick/revert: add scissors line on merge conflict 2019-04-19 12:05:36 +09:00
git-cherry.txt
git-citool.txt
git-clean.txt clean: disambiguate the definition of -d 2019-09-17 12:20:35 -07:00
git-clone.txt docs: git-clone: list short form of options first 2019-07-02 12:11:40 -07:00
git-column.txt git-column.txt: fix section header 2018-12-26 15:29:30 -08:00
git-commit-graph.txt Doc: refer to the "commit-graph file" with dash 2018-09-27 15:29:12 -07:00
git-commit-tree.txt commit-tree: utilize parse-options api 2019-03-08 10:31:24 +09:00
git-commit.txt git-commit.txt: better description what it does 2019-02-04 10:00:01 -08:00
git-config.txt Merge branch 'ma/asciidoctor-fixes-more' 2019-04-16 19:28:04 +09:00
git-count-objects.txt
git-credential-cache--daemon.txt
git-credential-cache.txt Use proper syntax for replaceables in command docs 2018-05-25 17:16:47 +09:00
git-credential-store.txt Use proper syntax for replaceables in command docs 2018-05-25 17:16:47 +09:00
git-credential.txt
git-cvsexportcommit.txt
git-cvsimport.txt
git-cvsserver.txt Use proper syntax for replaceables in command docs 2018-05-25 17:16:47 +09:00
git-daemon.txt doc: format pathnames and URLs as monospace. 2019-03-13 11:14:22 +09:00
git-describe.txt describe doc: remove '7-char' abbreviation reference 2019-04-08 17:24:51 +09:00
git-diff-files.txt
git-diff-index.txt doc: keep first level section header in upper case 2018-05-02 17:03:33 +09:00
git-diff-tree.txt Documentation/git-diff-tree.txt: fix formatting 2019-04-01 15:17:47 +09:00
git-diff.txt doc: tidy asciidoc style 2019-01-23 11:37:29 -08:00
git-difftool.txt difftool: fallback on merge.guitool 2019-05-13 23:11:59 +09:00
git-fast-export.txt fast-export: add a --show-original-ids option to show original names 2018-11-17 18:43:52 +09:00
git-fast-import.txt Merge branch 'ab/gc-docs' 2019-04-25 16:41:18 +09:00
git-fetch-pack.txt Documentation: fix several one-character-off spelling errors 2018-04-09 14:15:02 +09:00
git-fetch.txt doc: tidy asciidoc style 2019-01-23 11:37:29 -08:00
git-filter-branch.txt doc: format pathnames and URLs as monospace. 2019-03-13 11:14:22 +09:00
git-fmt-merge-msg.txt config.txt: move fmt-merge-msg-config.txt to config/ 2018-10-29 10:17:01 +09:00
git-for-each-ref.txt ref-filter: add docs for new options 2018-12-28 10:08:11 -08:00
git-format-patch.txt doc: tidy asciidoc style 2019-01-23 11:37:29 -08:00
git-fsck-objects.txt
git-fsck.txt Documentation/git-fsck.txt: include fsck.* config variables 2019-07-29 10:41:18 -07:00
git-gc.txt gc docs: remove incorrect reference to gc.auto=0 2019-04-08 17:01:10 +09:00
git-get-tar-commit-id.txt
git-grep.txt Documentation: turn middle-of-line tabs into spaces 2019-03-07 09:25:32 +09:00
git-gui.txt
git-hash-object.txt hash-object doc: stop mentioning git-cvsimport 2019-05-28 10:47:42 -07:00
git-help.txt doc: format pathnames and URLs as monospace. 2019-03-13 11:14:22 +09:00
git-http-backend.txt Documentation: turn middle-of-line tabs into spaces 2019-03-07 09:25:32 +09:00
git-http-fetch.txt http-fetch: make -a standard behaviour 2018-04-24 10:55:02 +09:00
git-http-push.txt doc: keep first level section header in upper case 2018-05-02 17:03:33 +09:00
git-imap-send.txt git-imap-send.txt: move imap.* to a separate file 2018-10-29 10:17:02 +09:00
git-index-pack.txt doc: keep first level section header in upper case 2018-05-02 17:03:33 +09:00
git-init-db.txt
git-init.txt Merge branch 'km/init-doc-typofix' 2019-02-06 22:05:21 -08:00
git-instaweb.txt git-instaweb: add Python builtin http.server support 2019-01-28 10:57:44 -08:00
git-interpret-trailers.txt interpret-trailers.txt: start the desc line with a capital letter 2019-04-01 15:49:47 +09:00
git-log.txt Add 'human' date format documentation 2019-01-22 14:16:17 -08:00
git-ls-files.txt doc/ls-files: put nested list for "-t" option into block 2019-04-23 10:25:04 +09:00
git-ls-remote.txt Documentation: turn middle-of-line tabs into spaces 2019-03-07 09:25:32 +09:00
git-ls-tree.txt doc: format pathnames and URLs as monospace. 2019-03-13 11:14:22 +09:00
git-mailinfo.txt
git-mailsplit.txt
git-merge-base.txt doc: fix ASCII art tab spacing 2018-10-23 12:23:09 +09:00
git-merge-file.txt
git-merge-index.txt
git-merge-one-file.txt
git-merge-tree.txt
git-merge.txt merge: tweak --rerere-autoupdate documentation 2019-03-18 10:24:58 +09:00
git-mergetool--lib.txt mergetool: use get_merge_tool function 2019-05-13 23:11:59 +09:00
git-mergetool.txt mergetool: fallback to tool when guitool unavailable 2019-05-13 23:11:59 +09:00
git-mktag.txt
git-mktree.txt Documentation: normalize spelling of 'normalised' 2018-04-09 14:15:07 +09:00
git-multi-pack-index.txt multi-pack-index: add 'verify' verb 2018-09-17 13:49:38 -07:00
git-mv.txt
git-name-rev.txt doc: keep first level section header in upper case 2018-05-02 17:03:33 +09:00
git-notes.txt Documentation: turn middle-of-line tabs into spaces 2019-03-07 09:25:32 +09:00
git-p4.txt doc: tidy asciidoc style 2019-01-23 11:37:29 -08:00
git-pack-objects.txt list-objects: consume sparse tree walk 2019-01-17 13:44:39 -08:00
git-pack-redundant.txt
git-pack-refs.txt
git-parse-remote.txt
git-patch-id.txt
git-prune-packed.txt
git-prune.txt doc: keep first level section header in upper case 2018-05-02 17:03:33 +09:00
git-pull.txt docs: say that --rebase=preserve is deprecated 2019-05-28 13:22:34 -07:00
git-push.txt push doc: document the DWYM behavior pushing to unqualified <dst> 2018-11-14 15:27:56 +09:00
git-quiltimport.txt git-quiltimport: add --keep-non-patch option 2019-01-07 15:29:34 -08:00
git-range-diff.txt range-diff doc: add a section about output stability 2018-11-12 12:05:38 +09:00
git-read-tree.txt Merge branch 'nd/checkout-m' 2019-04-25 16:41:14 +09:00
git-rebase.txt Merge branch 'js/rebase-deprecate-preserve-merges' 2019-05-30 10:50:45 -07:00
git-receive-pack.txt doc: keep first level section header in upper case 2018-05-02 17:03:33 +09:00
git-reflog.txt reflog expire: cover reflog from all worktrees 2018-10-22 13:32:54 +09:00
git-remote-ext.txt Merge branch 'js/check-docs-exe' 2019-04-22 11:14:46 +09:00
git-remote-fd.txt docs: move gitremote-helpers into section 7 2019-04-01 14:00:53 +09:00
git-remote-helpers.txto docs: move gitremote-helpers into section 7 2019-04-01 14:00:53 +09:00
git-remote.txt Merge branch 'nd/remote-update-doc' 2018-06-04 21:39:49 +09:00
git-repack.txt Merge branch 'cc/delta-islands' 2018-09-17 13:53:55 -07:00
git-replace.txt replace: introduce --convert-graft-file 2018-04-30 11:12:30 +09:00
git-request-pull.txt doc: keep first level section header in upper case 2018-05-02 17:03:33 +09:00
git-rerere.txt rerere doc: quote rerere.enabled 2019-04-08 17:23:25 +09:00
git-reset.txt Merge branch 'dl/reset-doc-no-wrt-abbrev' 2019-04-10 02:14:21 +09:00
git-rev-list.txt rev-list: add list-objects filtering support 2017-11-22 14:11:57 +09:00
git-rev-parse.txt Use proper syntax for replaceables in command docs 2018-05-25 17:16:47 +09:00
git-revert.txt cherry-pick/revert: add scissors line on merge conflict 2019-04-19 12:05:36 +09:00
git-rm.txt
git-send-email.txt send-email: update documentation of required Perl modules 2019-05-31 14:41:41 -07:00
git-send-pack.txt doc: keep first level section header in upper case 2018-05-02 17:03:33 +09:00
git-sh-i18n--envsubst.txt
git-sh-i18n.txt
git-sh-setup.txt
git-shell.txt doc: keep first level section header in upper case 2018-05-02 17:03:33 +09:00
git-shortlog.txt git-[short]log.txt: unify quoted standalone -- 2018-04-18 12:49:26 +09:00
git-show-branch.txt Documentation/git-show-branch: avoid literal {apostrophe} 2019-04-10 12:05:03 +09:00
git-show-index.txt show-index: update documentation for index v2 2018-05-29 00:28:22 +09:00
git-show-ref.txt git-show-ref.txt: fix order of flags 2019-01-10 10:29:05 -08:00
git-show.txt Use proper syntax for replaceables in command docs 2018-05-25 17:16:47 +09:00
git-stage.txt
git-stash.txt stash: mention options in show synopsis 2019-03-07 09:41:40 +09:00
git-status.txt Documentation/git-status: fix titles in porcelain v2 section 2019-04-01 17:46:26 +09:00
git-stripspace.txt
git-submodule.txt Merge branch 'dl/submodule-set-branch' 2019-04-25 16:41:18 +09:00
git-svn.txt Merge branch 'tz/git-svn-doc-markup-fix' 2019-05-09 00:37:23 +09:00
git-symbolic-ref.txt
git-tag.txt doc: tidy asciidoc style 2019-01-23 11:37:29 -08:00
git-tools.txt
git-unpack-file.txt
git-unpack-objects.txt
git-update-index.txt Merge branch 'jc/update-index-doc' 2018-08-20 11:33:50 -07:00
git-update-ref.txt Merge branch 'ah/doc-updates' into maint 2018-11-21 22:58:07 +09:00
git-update-server-info.txt
git-upload-archive.txt
git-upload-pack.txt doc: tidy asciidoc style 2019-01-23 11:37:29 -08:00
git-var.txt doc: keep first level section header in upper case 2018-05-02 17:03:33 +09:00
git-verify-commit.txt
git-verify-pack.txt
git-verify-tag.txt
git-web--browse.txt doc: format pathnames and URLs as monospace. 2019-03-13 11:14:22 +09:00
git-whatchanged.txt
git-worktree.txt doc: fix typos in man pages 2019-03-18 14:45:21 +09:00
git-write-tree.txt
git.txt Document that 'git -C ""' works and doesn't change directory 2019-07-01 10:42:49 -07:00
gitattributes.txt Merge branch 'ab/doc-misc-typofixes' 2019-04-16 19:28:08 +09:00
gitcli.txt Use proper syntax for replaceables in command docs 2018-05-25 17:16:47 +09:00
gitcore-tutorial.txt
gitcredentials.txt doc: clarify gitcredentials path component matching 2018-09-27 15:24:50 -07:00
gitcvs-migration.txt
gitdiffcore.txt log -G: ignore binary files 2018-12-26 14:59:37 -08:00
giteveryday.txt Documentation: spelling and grammar fixes 2018-06-22 14:26:23 -07:00
gitglossary.txt
githooks.txt Merge branch 'bp/post-index-change-hook' 2019-04-25 16:41:11 +09:00
gitignore.txt Merge branch 'an/ignore-doc-update' into maint 2019-07-25 14:27:13 -07:00
gitk.txt doc: format pathnames and URLs as monospace. 2019-03-13 11:14:22 +09:00
gitmodules.txt doc: format pathnames and URLs as monospace. 2019-03-13 11:14:22 +09:00
gitnamespaces.txt
gitremote-helpers.txt Merge branch 'js/check-docs-exe' 2019-04-22 11:14:46 +09:00
gitrepository-layout.txt doc: format pathnames and URLs as monospace. 2019-03-13 11:14:22 +09:00
gitrevisions.txt push doc: correct lies about how push refspecs work 2018-08-31 14:04:06 -07:00
gitsubmodules.txt gitsubmodules: align html and nroff lists 2019-05-28 09:42:06 -07:00
gittutorial-2.txt
gittutorial.txt
gitweb.conf.txt Merge branch 'cb/doco-mono' 2019-04-22 11:14:45 +09:00
gitweb.txt doc: don't use git.kernel.org as example gitweb URL 2019-06-24 12:37:21 -07:00
gitworkflows.txt Merge branch 'km/doc-workflows-typofix' 2018-06-18 10:18:42 -07:00
glossary-content.txt Merge branch 'tg/glossary-overlay' 2019-04-16 19:28:07 +09:00
howto-index.sh
i18n.txt
install-doc-quick.sh install-doc-quick: allow specifying what ref to install 2017-12-12 16:49:40 -08:00
install-webdoc.sh
line-range-format.txt
lint-gitlink.perl
mailmap.txt
Makefile Merge branch 'js/misc-doc-fixes' 2019-05-09 00:37:27 +09:00
manpage-1.72.xsl
manpage-base-url.xsl.in
manpage-base.xsl
manpage-bold-literal.xsl
manpage-normal.xsl
manpage-quote-apos.xsl
manpage-suppress-sp.xsl
merge-options.txt Merge branch 'vv/merge-squash-with-explicit-commit' into maint 2019-07-25 14:27:10 -07:00
merge-strategies.txt merge: add merge.renames config setting 2018-05-08 16:19:41 +09:00
pretty-formats.txt Merge branch 'aw/pretty-trailers' 2019-03-07 09:59:52 +09:00
pretty-options.txt
pull-fetch-param.txt fetch doc: correct grammar in --force docs 2018-09-20 09:40:03 -07:00
rev-list-options.txt list-objects-filter: disable 'sparse:path' filters 2019-05-29 11:05:34 -07:00
revisions.txt Merge branch 'dl/rev-tilde-doc-clarify' 2019-05-13 23:50:34 +09:00
sequencer.txt doc: format pathnames and URLs as monospace. 2019-03-13 11:14:22 +09:00
SubmittingPatches doc: format pathnames and URLs as monospace. 2019-03-13 11:14:22 +09:00
texi.xsl
trace2-target-values.txt trace2: update docs to describe system/global config settings 2019-04-16 13:37:07 +09:00
transfer-data-leaks.txt
urls-remotes.txt
urls.txt docs: move gitremote-helpers into section 7 2019-04-01 14:00:53 +09:00
user-manual.conf
user-manual.txt checkout: describe_detached_head: remove ellipsis after committish 2017-12-06 07:32:40 -08:00