annotate hgext/purge.py @ 25881:9de443515f1d stable

help: scripting help topic There are a lot of non-human consumers of Mercurial. And the challenges and considerations for machines consuming Mercurial is significantly different from what humans face. I think there are enough special considerations around how machines consume Mercurial that a dedicated help topic is warranted. I concede the audience for this topic is probably small compared to the general audience. However, lots of normal Mercurial users do things like create one-off shell scripts for common workflows that I think this is useful enough to be in the install (as opposed to, say, a wiki page - which most users will likely never find). This text is by no means perfect. But you have to start somewhere. I think I did cover the important parts, though.
author Gregory Szorc <gregory.szorc@gmail.com>
date Sat, 18 Jul 2015 17:10:28 -0700
parents 80c5b2666a96
children 4b0fc75f9403
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
2364
f368a1c302d5 Initial commit
demian@gaudron.lan
parents:
diff changeset
1 # Copyright (C) 2006 - Marco Barisione <marco@barisione.org>
f368a1c302d5 Initial commit
demian@gaudron.lan
parents:
diff changeset
2 #
8936
1de6e7e1bb9f change wiki/bts URLs to point to new hostname
Dirkjan Ochtman <dirkjan@ochtman.nl>
parents: 8934
diff changeset
3 # This is a small extension for Mercurial (http://mercurial.selenic.com/)
2364
f368a1c302d5 Initial commit
demian@gaudron.lan
parents:
diff changeset
4 # that removes files not known to mercurial
f368a1c302d5 Initial commit
demian@gaudron.lan
parents:
diff changeset
5 #
9270
00cc7fa0c0c6 purge: wrap docstrings at 70 characters
Martin Geisler <mg@lazybytes.net>
parents: 9215
diff changeset
6 # This program was inspired by the "cvspurge" script contained in CVS
00cc7fa0c0c6 purge: wrap docstrings at 70 characters
Martin Geisler <mg@lazybytes.net>
parents: 9215
diff changeset
7 # utilities (http://www.red-bean.com/cvsutils/).
4154
15cd36db4230 Delete the README for purge, putting the useful informations in comments
Emanuele Aina <em@nerd.ocracy.org>
parents: 4153
diff changeset
8 #
15cd36db4230 Delete the README for purge, putting the useful informations in comments
Emanuele Aina <em@nerd.ocracy.org>
parents: 4153
diff changeset
9 # For help on the usage of "hg purge" use:
15cd36db4230 Delete the README for purge, putting the useful informations in comments
Emanuele Aina <em@nerd.ocracy.org>
parents: 4153
diff changeset
10 # hg help purge
15cd36db4230 Delete the README for purge, putting the useful informations in comments
Emanuele Aina <em@nerd.ocracy.org>
parents: 4153
diff changeset
11 #
2364
f368a1c302d5 Initial commit
demian@gaudron.lan
parents:
diff changeset
12 # This program is free software; you can redistribute it and/or modify
f368a1c302d5 Initial commit
demian@gaudron.lan
parents:
diff changeset
13 # it under the terms of the GNU General Public License as published by
f368a1c302d5 Initial commit
demian@gaudron.lan
parents:
diff changeset
14 # the Free Software Foundation; either version 2 of the License, or
f368a1c302d5 Initial commit
demian@gaudron.lan
parents:
diff changeset
15 # (at your option) any later version.
f368a1c302d5 Initial commit
demian@gaudron.lan
parents:
diff changeset
16 #
f368a1c302d5 Initial commit
demian@gaudron.lan
parents:
diff changeset
17 # This program is distributed in the hope that it will be useful,
f368a1c302d5 Initial commit
demian@gaudron.lan
parents:
diff changeset
18 # but WITHOUT ANY WARRANTY; without even the implied warranty of
f368a1c302d5 Initial commit
demian@gaudron.lan
parents:
diff changeset
19 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
f368a1c302d5 Initial commit
demian@gaudron.lan
parents:
diff changeset
20 # GNU General Public License for more details.
f368a1c302d5 Initial commit
demian@gaudron.lan
parents:
diff changeset
21 #
f368a1c302d5 Initial commit
demian@gaudron.lan
parents:
diff changeset
22 # You should have received a copy of the GNU General Public License
15782
7de7630053cb Remove FSF mailing address from GPL headers
Martin Geisler <mg@aragost.com>
parents: 14671
diff changeset
23 # along with this program; if not, see <http://www.gnu.org/licenses/>.
2364
f368a1c302d5 Initial commit
demian@gaudron.lan
parents:
diff changeset
24
8934
9dda4c73fc3b extensions: change descriptions for extensions providing a few commands
Dirkjan Ochtman <dirkjan@ochtman.nl>
parents: 8894
diff changeset
25 '''command to delete untracked files from the working directory'''
8873
e872ef2e6758 help: add/fix docstrings for a bunch of extensions
Dirkjan Ochtman <dirkjan@ochtman.nl>
parents: 8866
diff changeset
26
14322
a90131b85fd8 scmutil: drop aliases in cmdutil for match functions
Matt Mackall <mpm@selenic.com>
parents: 14310
diff changeset
27 from mercurial import util, commands, cmdutil, scmutil
4121
d250076824e3 Use the mercurial i18n infrastructure in the purge extension
Emanuele Aina <em@nerd.ocracy.org>
parents: 4120
diff changeset
28 from mercurial.i18n import _
21994
c6e1f2c6d5f1 purge: drop stat import
Matt Mackall <mpm@selenic.com>
parents: 21983
diff changeset
29 import os
2364
f368a1c302d5 Initial commit
demian@gaudron.lan
parents:
diff changeset
30
14310
c16ec14d44b6 purge: use cmdutil.command decorator
Adrian Buehlmann <adrian@cadifra.com>
parents: 10973
diff changeset
31 cmdtable = {}
c16ec14d44b6 purge: use cmdutil.command decorator
Adrian Buehlmann <adrian@cadifra.com>
parents: 10973
diff changeset
32 command = cmdutil.command(cmdtable)
25186
80c5b2666a96 extensions: document that `testedwith = 'internal'` is special
Augie Fackler <augie@google.com>
parents: 22920
diff changeset
33 # Note for extension authors: ONLY specify testedwith = 'internal' for
80c5b2666a96 extensions: document that `testedwith = 'internal'` is special
Augie Fackler <augie@google.com>
parents: 22920
diff changeset
34 # extensions which SHIP WITH MERCURIAL. Non-mainline extensions should
80c5b2666a96 extensions: document that `testedwith = 'internal'` is special
Augie Fackler <augie@google.com>
parents: 22920
diff changeset
35 # be specifying the version(s) of Mercurial they are tested with, or
80c5b2666a96 extensions: document that `testedwith = 'internal'` is special
Augie Fackler <augie@google.com>
parents: 22920
diff changeset
36 # leave the attribute unspecified.
16743
38caf405d010 hgext: mark all first-party extensions as such
Augie Fackler <raf@durin42.com>
parents: 15782
diff changeset
37 testedwith = 'internal'
14310
c16ec14d44b6 purge: use cmdutil.command decorator
Adrian Buehlmann <adrian@cadifra.com>
parents: 10973
diff changeset
38
c16ec14d44b6 purge: use cmdutil.command decorator
Adrian Buehlmann <adrian@cadifra.com>
parents: 10973
diff changeset
39 @command('purge|clean',
c16ec14d44b6 purge: use cmdutil.command decorator
Adrian Buehlmann <adrian@cadifra.com>
parents: 10973
diff changeset
40 [('a', 'abort-on-err', None, _('abort if an error occurs')),
c16ec14d44b6 purge: use cmdutil.command decorator
Adrian Buehlmann <adrian@cadifra.com>
parents: 10973
diff changeset
41 ('', 'all', None, _('purge ignored files too')),
21853
8127b9e798b1 purge: add options for deleting only files or only directories
Ben Kehoe <benk@berkeley.edu>
parents: 20565
diff changeset
42 ('', 'dirs', None, _('purge empty directories')),
8127b9e798b1 purge: add options for deleting only files or only directories
Ben Kehoe <benk@berkeley.edu>
parents: 20565
diff changeset
43 ('', 'files', None, _('purge files')),
14310
c16ec14d44b6 purge: use cmdutil.command decorator
Adrian Buehlmann <adrian@cadifra.com>
parents: 10973
diff changeset
44 ('p', 'print', None, _('print filenames instead of deleting them')),
c16ec14d44b6 purge: use cmdutil.command decorator
Adrian Buehlmann <adrian@cadifra.com>
parents: 10973
diff changeset
45 ('0', 'print0', None, _('end filenames with NUL, for use with xargs'
c16ec14d44b6 purge: use cmdutil.command decorator
Adrian Buehlmann <adrian@cadifra.com>
parents: 10973
diff changeset
46 ' (implies -p/--print)')),
c16ec14d44b6 purge: use cmdutil.command decorator
Adrian Buehlmann <adrian@cadifra.com>
parents: 10973
diff changeset
47 ] + commands.walkopts,
c16ec14d44b6 purge: use cmdutil.command decorator
Adrian Buehlmann <adrian@cadifra.com>
parents: 10973
diff changeset
48 _('hg purge [OPTION]... [DIR]...'))
6573
44cd348e6529 purge: eliminate dopurge
Matt Mackall <mpm@selenic.com>
parents: 6212
diff changeset
49 def purge(ui, repo, *dirs, **opts):
7605
3e592067515d 1 file changed, 7 insertions(+), 9 deletions(-)
Benjamin Pollack <benjamin@bitquabit.com>
parents: 7570
diff changeset
50 '''removes files not tracked by Mercurial
6573
44cd348e6529 purge: eliminate dopurge
Matt Mackall <mpm@selenic.com>
parents: 6212
diff changeset
51
9270
00cc7fa0c0c6 purge: wrap docstrings at 70 characters
Martin Geisler <mg@lazybytes.net>
parents: 9215
diff changeset
52 Delete files not known to Mercurial. This is useful to test local
00cc7fa0c0c6 purge: wrap docstrings at 70 characters
Martin Geisler <mg@lazybytes.net>
parents: 9215
diff changeset
53 and uncommitted changes in an otherwise-clean source tree.
6573
44cd348e6529 purge: eliminate dopurge
Matt Mackall <mpm@selenic.com>
parents: 6212
diff changeset
54
21853
8127b9e798b1 purge: add options for deleting only files or only directories
Ben Kehoe <benk@berkeley.edu>
parents: 20565
diff changeset
55 This means that purge will delete the following by default:
9215
f6a880fa9cd7 purge: fix formatting of lists with proper reST markup
Martin Geisler <mg@lazybytes.net>
parents: 9072
diff changeset
56
10973
49a07f441496 Use hg role in help strings
Martin Geisler <mg@aragost.com>
parents: 9270
diff changeset
57 - Unknown files: files marked with "?" by :hg:`status`
9270
00cc7fa0c0c6 purge: wrap docstrings at 70 characters
Martin Geisler <mg@lazybytes.net>
parents: 9215
diff changeset
58 - Empty directories: in fact Mercurial ignores directories unless
00cc7fa0c0c6 purge: wrap docstrings at 70 characters
Martin Geisler <mg@lazybytes.net>
parents: 9215
diff changeset
59 they contain files under source control management
9215
f6a880fa9cd7 purge: fix formatting of lists with proper reST markup
Martin Geisler <mg@lazybytes.net>
parents: 9072
diff changeset
60
6573
44cd348e6529 purge: eliminate dopurge
Matt Mackall <mpm@selenic.com>
parents: 6212
diff changeset
61 But it will leave untouched:
9215
f6a880fa9cd7 purge: fix formatting of lists with proper reST markup
Martin Geisler <mg@lazybytes.net>
parents: 9072
diff changeset
62
f6a880fa9cd7 purge: fix formatting of lists with proper reST markup
Martin Geisler <mg@lazybytes.net>
parents: 9072
diff changeset
63 - Modified and unmodified tracked files
f6a880fa9cd7 purge: fix formatting of lists with proper reST markup
Martin Geisler <mg@lazybytes.net>
parents: 9072
diff changeset
64 - Ignored files (unless --all is specified)
10973
49a07f441496 Use hg role in help strings
Martin Geisler <mg@aragost.com>
parents: 9270
diff changeset
65 - New files added to the repository (with :hg:`add`)
6573
44cd348e6529 purge: eliminate dopurge
Matt Mackall <mpm@selenic.com>
parents: 6212
diff changeset
66
21853
8127b9e798b1 purge: add options for deleting only files or only directories
Ben Kehoe <benk@berkeley.edu>
parents: 20565
diff changeset
67 The --files and --dirs options can be used to direct purge to delete
8127b9e798b1 purge: add options for deleting only files or only directories
Ben Kehoe <benk@berkeley.edu>
parents: 20565
diff changeset
68 only files, only directories, or both. If neither option is given,
8127b9e798b1 purge: add options for deleting only files or only directories
Ben Kehoe <benk@berkeley.edu>
parents: 20565
diff changeset
69 both will be deleted.
8127b9e798b1 purge: add options for deleting only files or only directories
Ben Kehoe <benk@berkeley.edu>
parents: 20565
diff changeset
70
6573
44cd348e6529 purge: eliminate dopurge
Matt Mackall <mpm@selenic.com>
parents: 6212
diff changeset
71 If directories are given on the command line, only files in these
44cd348e6529 purge: eliminate dopurge
Matt Mackall <mpm@selenic.com>
parents: 6212
diff changeset
72 directories are considered.
44cd348e6529 purge: eliminate dopurge
Matt Mackall <mpm@selenic.com>
parents: 6212
diff changeset
73
9270
00cc7fa0c0c6 purge: wrap docstrings at 70 characters
Martin Geisler <mg@lazybytes.net>
parents: 9215
diff changeset
74 Be careful with purge, as you could irreversibly delete some files
00cc7fa0c0c6 purge: wrap docstrings at 70 characters
Martin Geisler <mg@lazybytes.net>
parents: 9215
diff changeset
75 you forgot to add to the repository. If you only want to print the
00cc7fa0c0c6 purge: wrap docstrings at 70 characters
Martin Geisler <mg@lazybytes.net>
parents: 9215
diff changeset
76 list of files that this program would delete, use the --print
00cc7fa0c0c6 purge: wrap docstrings at 70 characters
Martin Geisler <mg@lazybytes.net>
parents: 9215
diff changeset
77 option.
6573
44cd348e6529 purge: eliminate dopurge
Matt Mackall <mpm@selenic.com>
parents: 6212
diff changeset
78 '''
44cd348e6529 purge: eliminate dopurge
Matt Mackall <mpm@selenic.com>
parents: 6212
diff changeset
79 act = not opts['print']
6757
55c71226eceb purge: cleanup
Matt Mackall <mpm@selenic.com>
parents: 6754
diff changeset
80 eol = '\n'
55c71226eceb purge: cleanup
Matt Mackall <mpm@selenic.com>
parents: 6754
diff changeset
81 if opts['print0']:
55c71226eceb purge: cleanup
Matt Mackall <mpm@selenic.com>
parents: 6754
diff changeset
82 eol = '\0'
55c71226eceb purge: cleanup
Matt Mackall <mpm@selenic.com>
parents: 6754
diff changeset
83 act = False # --print0 implies --print
21853
8127b9e798b1 purge: add options for deleting only files or only directories
Ben Kehoe <benk@berkeley.edu>
parents: 20565
diff changeset
84 removefiles = opts['files']
8127b9e798b1 purge: add options for deleting only files or only directories
Ben Kehoe <benk@berkeley.edu>
parents: 20565
diff changeset
85 removedirs = opts['dirs']
8127b9e798b1 purge: add options for deleting only files or only directories
Ben Kehoe <benk@berkeley.edu>
parents: 20565
diff changeset
86 if not removefiles and not removedirs:
8127b9e798b1 purge: add options for deleting only files or only directories
Ben Kehoe <benk@berkeley.edu>
parents: 20565
diff changeset
87 removefiles = True
8127b9e798b1 purge: add options for deleting only files or only directories
Ben Kehoe <benk@berkeley.edu>
parents: 20565
diff changeset
88 removedirs = True
2364
f368a1c302d5 Initial commit
demian@gaudron.lan
parents:
diff changeset
89
4153
af72395580e8 Delete the Purge class, refactoring Purge.purge() in dopurge()
Emanuele Aina <faina.mail@tiscali.it>
parents: 4152
diff changeset
90 def remove(remove_func, name):
af72395580e8 Delete the Purge class, refactoring Purge.purge() in dopurge()
Emanuele Aina <faina.mail@tiscali.it>
parents: 4152
diff changeset
91 if act:
af72395580e8 Delete the Purge class, refactoring Purge.purge() in dopurge()
Emanuele Aina <faina.mail@tiscali.it>
parents: 4152
diff changeset
92 try:
7570
e05aa73ce2b7 use repo.wjoin(f) instead of os.path.join(repo.root, f)
Martin Geisler <mg@daimi.au.dk>
parents: 7280
diff changeset
93 remove_func(repo.wjoin(name))
7280
810ca383da9c remove unused variables
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents: 6762
diff changeset
94 except OSError:
6757
55c71226eceb purge: cleanup
Matt Mackall <mpm@selenic.com>
parents: 6754
diff changeset
95 m = _('%s cannot be removed') % name
55c71226eceb purge: cleanup
Matt Mackall <mpm@selenic.com>
parents: 6754
diff changeset
96 if opts['abort_on_err']:
55c71226eceb purge: cleanup
Matt Mackall <mpm@selenic.com>
parents: 6754
diff changeset
97 raise util.Abort(m)
55c71226eceb purge: cleanup
Matt Mackall <mpm@selenic.com>
parents: 6754
diff changeset
98 ui.warn(_('warning: %s\n') % m)
4153
af72395580e8 Delete the Purge class, refactoring Purge.purge() in dopurge()
Emanuele Aina <faina.mail@tiscali.it>
parents: 4152
diff changeset
99 else:
af72395580e8 Delete the Purge class, refactoring Purge.purge() in dopurge()
Emanuele Aina <faina.mail@tiscali.it>
parents: 4152
diff changeset
100 ui.write('%s%s' % (name, eol))
4151
337010e50dcd Use nested functions instead of object methods
Emanuele Aina <faina.mail@tiscali.it>
parents: 4150
diff changeset
101
14671
35c2cc322ba8 scmutil: switch match users to supplying contexts
Matt Mackall <mpm@selenic.com>
parents: 14322
diff changeset
102 match = scmutil.match(repo[None], dirs, opts)
22265
fe22d86a8992 purge: avoid full walks when directories aren't purged
Siddharth Agarwal <sid0@fb.com>
parents: 21994
diff changeset
103 if removedirs:
fe22d86a8992 purge: avoid full walks when directories aren't purged
Siddharth Agarwal <sid0@fb.com>
parents: 21994
diff changeset
104 directories = []
fe22d86a8992 purge: avoid full walks when directories aren't purged
Siddharth Agarwal <sid0@fb.com>
parents: 21994
diff changeset
105 match.explicitdir = match.traversedir = directories.append
6754
0b700faaef32 purge: use status
Matt Mackall <mpm@selenic.com>
parents: 6746
diff changeset
106 status = repo.status(match=match, ignored=opts['all'], unknown=True)
4147
691f9168a815 Make the purge extension use the statwalk walker from the dirstate object
Emanuele Aina <faina.mail@tiscali.it>
parents: 4121
diff changeset
107
21853
8127b9e798b1 purge: add options for deleting only files or only directories
Ben Kehoe <benk@berkeley.edu>
parents: 20565
diff changeset
108 if removefiles:
22920
e049338d1a7b purge: access status fields by name rather than index
Martin von Zweigbergk <martinvonz@gmail.com>
parents: 22265
diff changeset
109 for f in sorted(status.unknown + status.ignored):
21853
8127b9e798b1 purge: add options for deleting only files or only directories
Ben Kehoe <benk@berkeley.edu>
parents: 20565
diff changeset
110 if act:
8127b9e798b1 purge: add options for deleting only files or only directories
Ben Kehoe <benk@berkeley.edu>
parents: 20565
diff changeset
111 ui.note(_('removing file %s\n') % f)
21983
52d34d5415c9 purge: prefer util.unlink instead over own removefile
Christian Ebert <blacktrash@gmx.net>
parents: 21853
diff changeset
112 remove(util.unlink, f)
4147
691f9168a815 Make the purge extension use the statwalk walker from the dirstate object
Emanuele Aina <faina.mail@tiscali.it>
parents: 4121
diff changeset
113
21853
8127b9e798b1 purge: add options for deleting only files or only directories
Ben Kehoe <benk@berkeley.edu>
parents: 20565
diff changeset
114 if removedirs:
8127b9e798b1 purge: add options for deleting only files or only directories
Ben Kehoe <benk@berkeley.edu>
parents: 20565
diff changeset
115 for f in sorted(directories, reverse=True):
8127b9e798b1 purge: add options for deleting only files or only directories
Ben Kehoe <benk@berkeley.edu>
parents: 20565
diff changeset
116 if match(f) and not os.listdir(repo.wjoin(f)):
8127b9e798b1 purge: add options for deleting only files or only directories
Ben Kehoe <benk@berkeley.edu>
parents: 20565
diff changeset
117 if act:
8127b9e798b1 purge: add options for deleting only files or only directories
Ben Kehoe <benk@berkeley.edu>
parents: 20565
diff changeset
118 ui.note(_('removing directory %s\n') % f)
8127b9e798b1 purge: add options for deleting only files or only directories
Ben Kehoe <benk@berkeley.edu>
parents: 20565
diff changeset
119 remove(os.rmdir, f)