summaryrefslogtreecommitdiff
path: root/Documentation/git-clean.txt
AgeCommit message (Collapse)AuthorFilesLines
2019-10-11Merge branch 'en/clean-nested-with-ignored'Libravatar Junio C Hamano1-7/+9
"git clean" fixes. * en/clean-nested-with-ignored: dir: special case check for the possibility that pathspec is NULL clean: fix theoretical path corruption clean: rewrap overly long line clean: avoid removing untracked files in a nested git repository clean: disambiguate the definition of -d git-clean.txt: do not claim we will delete files with -n/--dry-run dir: add commentary explaining match_pathspec_item's return value dir: if our pathspec might match files under a dir, recurse into it dir: make the DO_MATCH_SUBMODULE code reusable for a non-submodule case dir: also check directories for matching pathspecs dir: fix off-by-one error in match_pathspec_item dir: fix typo in comment t7300: add testcases showing failure to clean specified pathspecs
2019-09-17clean: avoid removing untracked files in a nested git repositoryLibravatar Elijah Newren1-3/+3
Users expect files in a nested git repository to be left alone unless sufficiently forced (with two -f's). Unfortunately, in certain circumstances, git would delete both tracked (and possibly dirty) files and untracked files within a nested repository. To explain how this happens, let's contrast a couple cases. First, take the following example setup (which assumes we are already within a git repo): git init nested cd nested >tracked git add tracked git commit -m init >untracked cd .. In this setup, everything works as expected; running 'git clean -fd' will result in fill_directory() returning the following paths: nested/ nested/tracked nested/untracked and then correct_untracked_entries() would notice this can be compressed to nested/ and then since "nested/" is a directory, we would call remove_dirs("nested/", ...), which would check is_nonbare_repository_dir() and then decide to skip it. However, if someone also creates an ignored file: >nested/ignored then running 'git clean -fd' would result in fill_directory() returning the same paths: nested/ nested/tracked nested/untracked but correct_untracked_entries() will notice that we had ignored entries under nested/ and thus simplify this list to nested/tracked nested/untracked Since these are not directories, we do not call remove_dirs() which was the only place that had the is_nonbare_repository_dir() safety check -- resulting in us deleting both the untracked file and the tracked (and possibly dirty) file. One possible fix for this issue would be walking the parent directories of each path and checking if they represent nonbare repositories, but that would be wasteful. Even if we added caching of some sort, it's still a waste because we should have been able to check that "nested/" represented a nonbare repository before even descending into it in the first place. Add a DIR_SKIP_NESTED_GIT flag to dir_struct.flags and use it to prevent fill_directory() and friends from descending into nested git repos. With this change, we also modify two regression tests added in commit 91479b9c72f1 ("t7300: add tests to document behavior of clean and nested git", 2015-06-15). That commit, nor its series, nor the six previous iterations of that series on the mailing list discussed why those tests coded the expectation they did. In fact, it appears their purpose was simply to test _existing_ behavior to make sure that the performance changes didn't change the behavior. However, these two tests directly contradicted the manpage's claims that two -f's were required to delete files/directories under a nested git repository. While one could argue that the user gave an explicit path which matched files/directories that were within a nested repository, there's a slippery slope that becomes very difficult for users to understand once you go down that route (e.g. what if they specified "git clean -f -d '*.c'"?) It would also be hard to explain what the exact behavior was; avoid such problems by making it really simple. Also, clean up some grammar errors describing this functionality in the git-clean manpage. Finally, there are still a couple bugs with -ffd not cleaning out enough (e.g. missing the nested .git) and with -ffdX possibly cleaning out the wrong files (paying attention to outer .gitignore instead of inner). This patch does not address these cases at all (and does not change the behavior relative to those flags), it only fixes the handling when given a single -f. See https://public-inbox.org/git/20190905212043.GC32087@szeder.dev/ for more discussion of the -ffd[X?] bugs. Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-09-17clean: disambiguate the definition of -dLibravatar Elijah Newren1-4/+6
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 5b7570cfb41c ("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-17git-clean.txt: do not claim we will delete files with -n/--dry-runLibravatar Elijah Newren1-1/+1
It appears that the wrong option got included in the list of what will cause git-clean to actually take action. Correct the list. Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-07-09Merge branch 'nd/switch-and-restore'Libravatar Junio C Hamano1-1/+1
Two new commands "git switch" and "git restore" are introduced to split "checking out a branch to work on advancing its history" and "checking out paths out of the index and/or a tree-ish to work on advancing the current history" out of the single "git checkout" command. * nd/switch-and-restore: (46 commits) completion: disable dwim on "git switch -d" switch: allow to switch in the middle of bisect t2027: use test_must_be_empty Declare both git-switch and git-restore experimental help: move git-diff and git-reset to different groups doc: promote "git restore" user-manual.txt: prefer 'merge --abort' over 'reset --hard' completion: support restore t: add tests for restore restore: support --patch restore: replace --force with --ignore-unmerged restore: default to --source=HEAD when only --staged is specified restore: reject invalid combinations with --staged restore: add --worktree and --staged checkout: factor out worktree checkout code restore: disable overlay mode by default restore: make pathspec mandatory restore: take tree-ish from --source option instead checkout: split part of it to new command 'restore' doc: promote "git switch" ...
2019-05-07doc: promote "git restore"Libravatar Nguyễn Thái Ngọc Duy1-1/+1
The new command "git restore" (together with "git switch") are added to avoid the confusion of one-command-do-all "git checkout" for new users. They are also helpful to avoid ambiguous context. For these reasons, promote it everywhere possible. This includes documentation, suggestions/advice from other commands. One nice thing about git-restore is the ability to restore "everything", so it can be used in "git status" advice instead of both "git checkout" and "git reset". The three commands suggested by "git status" are add, rm and restore. "git checkout" is also removed from "git help" (i.e. it's no longer considered a commonly used command) Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-03-08git-clean.txt: clarify ignore pattern filesLibravatar Denton Liu1-6/+5
In the git-clean documentation, -x and -e documented .gitignore, $GIT_DIR/info/excludes but neglected to mention the file pointed to by core.excludesFile. Remove specific list of files and, instead, reference gitignore(5) documentation so that information is consolidated and the git-clean documentation is more precise. Reported-by: Robert P. J. Day <rpjday@crashcourse.ca> Helped-by: Martin Ågren <martin.agren@gmail.com> Helped-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Denton Liu <liu.denton@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-06-28doc: typeset short command-line options as literalLibravatar Matthieu Moy1-1/+1
It was common in our documentation to surround short option names with forward quotes, which renders as italic in HTML. Instead, use backquotes which renders as monospace. This is one more step toward conformance to Documentation/CodingGuidelines. This was obtained with: perl -pi -e "s/'(-[a-z])'/\`\$1\`/g" *.txt Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-02-09Documentation/git-clean.txt: don't mention deletion of .git/modules/*Libravatar Matt McCutchen1-3/+1
The latter half of this sentence, the removal of the submodules, was never done with (or without) double -f back when it was written, and we still do not do so. Signed-off-by: Matt McCutchen <matt@mattmccutchen.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-03-06Merge branch 'mr/doc-clean-f-f'Libravatar Junio C Hamano1-2/+6
Documentation update. * mr/doc-clean-f-f: Documentation/git-clean.txt: document that -f may need to be given twice
2015-02-26Documentation/git-clean.txt: document that -f may need to be given twiceLibravatar Mikko Rapeli1-2/+6
This is needed in build automation where the tree really needs to be reset to known state. Signed-off-by: Mikko Rapeli <mikko.rapeli@iki.fi> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-11-04Documentation: typofixesLibravatar Thomas Ackermann1-1/+1
In addition to fixing trivial and obvious typos, be careful about the following points: - Spell ASCII, URL and CRC in ALL CAPS; - Spell Linux as Capitalized; - Do not omit periods in "i.e." and "e.g.". Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-07-24Documentation/git-clean: fix description for rangeLibravatar Jiang Xin1-1/+1
The descriptions of "select by numbers" section for interactive git-clean are borrowed from git-add, and one sentence should be replaced. Signed-off-by: Jiang Xin <worldhello.net@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-06-26git-clean: add documentation for interactive git-cleanLibravatar Jiang Xin1-2/+63
Add new section "Interactive mode" for documentation of interactive git-clean. Signed-off-by: Jiang Xin <worldhello.net@gmail.com> Helped-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-06-26git-clean: add support for -i/--interactiveLibravatar Jiang Xin1-2/+8
Show what would be done and the user must confirm before actually cleaning. Would remove ... Would remove ... Would remove ... Remove [y/n]? Press "y" to start cleaning, and press "n" if you want to abort. Signed-off-by: Jiang Xin <worldhello.net@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-01Documentation: the name of the system is 'Git', not 'git'Libravatar Thomas Ackermann1-4/+4
Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-09-18Doc clean: add See Also linkLibravatar Philip Oakley1-0/+4
'git clean' is controlled by gitignore. Provide See Also link for it. Use of core.excludesfile is implied. Signed-off-by: Philip Oakley <philipoakley@iee.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-08-28Documentation: clarify "git clean -e <pattern>"Libravatar Junio C Hamano1-4/+6
The current explanation of -e can be misread as allowing the user to say I know 'git clean -XYZ' (substitute -XYZ with any option and/or parameter) will remove paths A, B, and C, and I want them all removed except for paths matching this pattern by adding '-e C' to the same command line, i.e. 'git clean -e C -XYZ'. But that is not what this option does. It augments the set of ignore rules from the command line, just like the same "-e <pattern>" argument does with the "ls-files" command (the user could probably pass "-e \!C" to tell the command to clean everything the command would normally remove, except for C). Also error out when both -x and -e are given with an explanation of what -e means---it is a symptom of misunderstanding what -e does. It also fixes small style nit in the parameter to add_exclude() call. The current code only works because EXC_CMDL happens to be defined as 0. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-03-11doc: drop author/documentation sections from most pagesLibravatar Jeff King1-6/+0
The point of these sections is generally to: 1. Give credit where it is due. 2. Give the reader an idea of where to ask questions or file bug reports. But they don't do a good job of either case. For (1), they are out of date and incomplete. A much more accurate answer can be gotten through shortlog or blame. For (2), the correct contact point is generally git@vger, and even if you wanted to cc the contact point, the out-of-date and incomplete fields mean you're likely sending to somebody useless. So let's drop the fields entirely from all manpages except git(1) itself. We already point people to the mailing list for bug reports there, and we can update the Authors section to give credit to the major contributors and point to shortlog and blame for more information. Each page has a "This is part of git" footer, so people can follow that to the main git manpage.
2010-07-20Add -e/--exclude to git-clean.Libravatar Jared Hance1-1/+7
With the -e/--exclude option for git-clean, a user can specify files that they haven't yet told git about, but either need for a short amount of time or plan to tell git about them later. This allows one to still use git-clean while these files are around without losing data. Signed-off-by: Jared Hance <jaredhance@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-02-04git-clean: fix the description of the default behaviorLibravatar Michael J Gruber1-2/+2
Currently, when called without -n and -f, git clean issues fatal: clean.requireForce not set and -n or -f not given; refusing to clean which leaves the user wondering why force is required when requireForce is not set. Looking up in git-clean(1) does not help because its description is wrong. Change it so that git clean issues fatal: clean.requireForce defaults to true and -n or -f not given; refusing to clean in this situation (and "...set to true..." when it is set) which makes it clearer that an unset config means true here, and adjust the documentation. Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-01-10Documentation: spell 'git cmd' without dash throughoutLibravatar Thomas Rast1-2/+2
The documentation was quite inconsistent when spelling 'git cmd' if it only refers to the program, not to some specific invocation syntax: both 'git-cmd' and 'git cmd' spellings exist. The current trend goes towards dashless forms, and there is precedent in 647ac70 (git-svn.txt: stop using dash-form of commands., 2009-07-07) to actively eliminate the dashed variants. Replace 'git-cmd' with 'git cmd' throughout, except where git-shell, git-cvsserver, git-upload-pack, git-receive-pack, and git-upload-archive are concerned, because those really live in the $PATH.
2009-08-29UI consistency: allow --force for where -f means forceLibravatar René Scharfe1-0/+1
git branch, checkout, clean, mv and tag all have an option -f to override certain checks. This patch makes them accept the long option --force as a synonym. While we're at it, document that checkout support --quiet as synonym for its short option -q. Signed-off-by: Rene Scharfe <rene.scharfe@lsrfire.ath.cx> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-07-29clean: require double -f options to nuke nested git repository and work treeLibravatar Junio C Hamano1-0/+3
When you have an embedded git work tree in your work tree (be it an orphaned submodule, or an independent checkout of an unrelated project), "git clean -d -f" blindly descended into it and removed everything. This is rarely what the user wants. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-05-06git-clean doc: the command only affects paths under $(cwd)Libravatar Junio C Hamano1-2/+2
Fredrik Skolmli and Thomas Rast noticed that it was left unstated that "git clean" ran from a subdirectory will not affect anything outside it, with or without path limiters. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-25Documentation: git-clean: make description more readableLibravatar Wesley J. Landaker1-5/+8
The existing text is a little bit awkward. This rewrites the description section to be more readable and friendly. Signed-off-by: Wesley J. Landaker <wjl@icecavern.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-25Documentation: git-clean: fix minor grammatical errorsLibravatar Wesley J. Landaker1-3/+3
There were a few minor grammatical errors that made this paragraph hard to read. This patch fixes the errors in a very minimal manner. Signed-off-by: Wesley J. Landaker <wjl@icecavern.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-30Make the DESCRIPTION match <x>... items in the SYNOPSISLibravatar Abhijit Menon-Sen1-3/+3
When the SYNOPSIS says e.g. "<path>...", it is nice if the DESCRIPTION also mentions "<path>..." and says the specified "paths" (note plural) are used for $whatever. This fixes the obvious mismatches. Signed-off-by: Abhijit Menon-Sen <ams@toroid.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-05manpages: italicize git command names (which were in teletype font)Libravatar Jonathan Nieder1-2/+2
The names of git commands are not meant to be entered at the commandline; they are just names. So we render them in italics, as is usual for command names in manpages. Using doit () { perl -e 'for (<>) { s/\`(git-[^\`.]*)\`/'\''\1'\''/g; print }' } for i in git*.txt config.txt diff*.txt blame*.txt fetch*.txt i18n.txt \ merge*.txt pretty*.txt pull*.txt rev*.txt urls*.txt do doit <"$i" >"$i+" && mv "$i+" "$i" done git diff . Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-01Documentation formatting and cleanupLibravatar Jonathan Nieder1-2/+2
Following what appears to be the predominant style, format names of commands and commandlines both as `teletype text`. While we're at it, add articles ("a" and "the") in some places, italicize the name of the command in the manual page synopsis line, and add a comma or two where it seems appropriate. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-01Documentation: be consistent about "git-" versus "git "Libravatar Jonathan Nieder1-1/+1
Since the git-* commands are not installed in $(bindir), using "git-command <parameters>" in examples in the documentation is not a good idea. On the other hand, it is nice to be able to refer to each command using one hyphenated word. (There is no escaping it, anyway: man page names cannot have spaces in them.) This patch retains the dash in naming an operation, command, program, process, or action. Complete command lines that can be entered at a shell (i.e., without options omitted) are made to use the dashless form. The changes consist only of replacing some spaces with hyphens and vice versa. After a "s/ /-/g", the unpatched and patched versions are identical. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-06-08Docs: add some long/short optionsLibravatar Stephan Beyer1-0/+2
Namely: git-clean.txt: --dry-run --quiet git-count-objects.txt: --verbose git-quiltimport.txt: -n git-remote.txt: -v --verbose Signed-off-by: Stephan Beyer <s-beyer@gmx.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-06-06documentation: move git(7) to git(1)Libravatar Christian Couder1-1/+1
As the "git" man page describes the "git" command at the end-user level, it seems better to move it to man section 1. Signed-off-by: Christian Couder <chriscool@tuxfamily.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-01-06Documentation: rename gitlink macro to linkgitLibravatar Dan McGee1-2/+2
Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-05-07Fix minor documentation errorsLibravatar Michael Spang1-1/+1
- git-ls-files.txt: typo in description of --ignored - git-clean.txt: s/forceRequire/requireForce/ Signed-off-by: Michael Spang <mspang@uwaterloo.ca> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-04-23Add clean.requireForce option, and add -f option to git-clean to override itLibravatar Josh Triplett1-1/+5
Add a new configuration option clean.requireForce. If set, git-clean will refuse to run, unless forced with the new -f option, or not acting due to -n. Signed-off-by: Josh Triplett <josh@freedesktop.org> Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-05-08Teach git-clean optional <paths>... parameters.Libravatar Junio C Hamano1-1/+4
When optional paths arguments are given, git-clean passes them to underlying git-ls-files; with this, you can say: git clean 'temp-*' to clean only the garbage files whose names begin with 'temp-'. Signed-off-by: Junio C Hamano <junkio@cox.net> Signed-off-by: Pavel Roskin <proski@gnu.org>
2006-04-05Add git-clean commandLibravatar Pavel Roskin1-0/+50
This command removes untracked files from the working tree. This implementation is based on cg-clean with some simplifications. The documentation is included. [jc: with trivial documentation fix, noticed by Jakub Narebski] Signed-off-by: Pavel Roskin <proski@gnu.org> Signed-off-by: Junio C Hamano <junkio@cox.net>