[perl #122820]

# New Ticket Created by  James E Keenan 
# Please include the string:  [perl #122820]
# in the subject line of all future correspondence about this issue. 
# <URL: https://rt.perl.org/Ticket/Display.html?id=122820 >


With this ticket I bring into RT the discussion that began on list starting at:
http://www.nntp.perl.org/group/perl.perl5.porters/2014/09/msg220237.html

In this post I summarize that discussion, present current documentation relevant to the problem and describe one policy question which needs to be resolved before a solution can be implemented.

I.  Discussion of Problem

Steve Hay initiated the discussion in the context of working on core on Win32:

#####
"I just noticed that after doing a "nmake distclean" there are still
many files left lying around that shouldn't be. Exactly which ones is
shown by running "git clean -dfx" afterwards: That should output
nothing, but instead cleaned up all the files below!

"distclean certainly used to work at some time in the (recent?) past."
#####

Subsequent posts confirmed that this problem is *not* limited to Win32 and has existed for some time.  Some have suggested that 'make distclean' be made an alias for 'git clean -dfx', but others have pointed out that you cannot and should not assume that one is always working within a git checkout.  'make distclean' presumably DTRT for Perl 5 core developers before we switched to git as our revision control system.  It should not have been allowed to fall into disrepair.

[My editorial comments:  There is no guarantee that git will be the last revision control system Perl will ever use, so we shouldn't tie ourselves too closely to it.  TMTOWTDI encourages this and prudence recommends this.  'git clean -dfx' may DTRT for *many* Perl 5 core developers *much* of the time, the mere fact that we are having this discussion indicates that it does not DTRT for all core developers all of the time.]

II.  Documentation of Current Functionality

A.  'make distclean'

'make distclean' is documented in INSTALL under the heading "Starting all over again":

#####
If you wish to rebuild perl from the same build directory, you should clean it out with the command 'make distclean' or 'make realclean'[.]  The only difference between the two is that 'make distclean' also removes your old config.sh and Policy.sh files. [Some paragraph reformatting -- jk.]
#####

B.  'git clean -dfx'

>From 'man git-clean' for Git 1.9.l:

#####
Cleans the working tree by recursively removing files that are not under version control, starting from the current directory.

Normally, only files unknown to Git are removed, but if the -x option is specified, ignored files are also removed. This can, for example, be useful to remove all build products.
#####

Here is what I believe to be the most relevant parts of the documentation of the three options:

#####
-d: Remove untracked directories in addition to untracked files.

-f: If the Git configuration variable clean.requireForce is not set to false, git clean will refuse to run unless given -f, -n or -i.

-x: This allows removing all untracked files, including build products. This can be used (possibly in conjunction with git reset) to create a pristine working directory to test a clean build.
#####

C.  Attachments

Attached are three files derived from a perl built on Linux x86_64 in blead.  'git clean -dfx' was run before a fetch from origin and rebase, then perl was configured only with '-des -Dusedevel', then perl was built and tested.

* Output from 'git clean -dfx' after from-scratch build: git.clean.dfx.txt

* Output from 'make distclean' after from-scratch build: make.distclean.txt

* Output from 'git clean -dfx' after 'make distclean' has been run: activated.after.make.distclean.git.clean.dfx.txt

Examination of the latter suggests that almost all of the files and directories which 'make distclean' is failing to remove and which we would presumably expect it to remove are found under 'lib/'.

III.  Policy Issues

A.  Scope of Defect

Are we in agreement that, given an otherwise pristine working directory, 'make distclean' should remove the same directories and files as 'git clean -dfx'?  In other words, after running 'make distclean' should a file like attachment activated.after.make.distclean.git.clean.dfx.txt be empty?

B.  Scope of 'make distclean' relative to 'git clean -dfx'

'make distclean' does not rely on the revision control system for the list of files to be removed.  It relies on MANIFEST, Makefile and its predecessors, etc.  As such, it is not documented to remove any files the user may have in the working directory which are not under revision control or are not build artifacts.

Suppose I had in my working directory a little shell script to configure a DEBUGGING build.

#####
$ cat mydebugconfigure.sh

#/bin/sh
./Configure -des -Dusedevel -DDEBUGGING
#####

'make distclean' would presumably *not* remove that shell script as it is neither under revision control nor a build artifact.

'git clean', however, treats the working directory primarily as a git checkout and -- particularly with '-dfx' -- aims to get that checkout back to a pristine state from git's point of view.  git's point of view is not necessarily perl's or the developer's point of view.  'git clean -dfx' would nuke that shell script wrapping around Configure.

Once we have corrected the defect in III.A. above, are we happy with the fact that 'make distclean' and 'git clean -dfx' have somewhat different objectives and hence achieve different results?

IV.  Summary

Once we've resolved III.A. and III.B., patches welcome!

Thank you very much.
Jim Keenan


-- 
James E Keenan (jkeenan@cpan.org)

• [perl #122820] by James E Keenan via RT
• Re: [perl #122820] by Craig A. Berry
• Re: [perl #122820] by Craig A. Berry
• [perl #122820] by James E Keenan