Stefan Sperling wrote:
> On Wed, Feb 03, 2010 at 12:52:25AM +0000, Julian Foad wrote:
> > I think the rule is (not just for 'svn add', but for all svn commands
> > that do this kind of ignoring):
> >
> > a file is ignored iff
> > (it matches the svn:ignore property or the global-ignores setting)
>
> Which svn:ignore property? The one placed at the parent directory
> of the path we are adding, right?
Yup.
> > and
> > (it is unversioned)
> > and
> > (it is encountered in recursion, rather than specified explicitly)
>
> Yes, which means we have to be running 'svn add path' where path is
> a directory. Else we never recurse.
>
> > and
> > (--no-ignores is not specified)
>
> Yes, that's how I understand the current behaviour, too, and is what
> I meant to say (but didn't). Thanks for phrasing it more clearly.
>
> > > So it looks like your new "no_svn_ignores" parameter is not needed.
> >
> > Or rather, I think the original change you were considering was
> > controlling whether to ignore files that are specified explicitly as
> > well as files that are encountered in recursion.
>
> Not just files, but directories also. Let's use 'path' as a collective
> term for either.
>
> > That extension could be
> > introduced in svn_client_addN(), but as that is a single-target API the
> > caller could implement the behaviour instead by choosing whether or not
> > to call it.
>
> Good point.
>
> > The svn subcommand, which takes multiple targets, could be extended to
> > control this behaviour. However, this behaviour (of not ignoring an
> > explicit target) was designed that way on purpose. It's not necessarily
> > the perfect UI, but it's fairly sensible and easy to describe. Are you
> > sure it is important to change the UI?
>
> The current behaviour may be intended, but if so it was not documented
> properly. We need to change either the UI or the documentation.
Yup - see below.
> I find the docstring of the API severly lacking.
> It does not explain the no_ignore parameter as well as you did above.
> At the very least, we need to update the docstring. As written, it
> implies that local_abspath will never be added if it matches any
> ignores (global or from the svn:ignore property).
In r906091 I have documented (thoroughly, I think) the current behaviour
of the client add, import and status APIs.
> However, I also think that the current behaviour is harder to explain
> than the suggested new behaviour. The currently documented (but not
> implemented) behaviour is pretty straightforward -- there are no exceptions.
> If it is unversioned and matches either the global or svn:ignore lists,
> and --no-ignores is not specified, it will not be added. Full stop.
>
> We have users who have read the relevant sections of the book, but still
> don't understand why svn is adding files they don't want to be added.
> In the case I saw being reported, the user was listing them on the command
> line driven by a script or something.
>
> This is because the output of 'svn help add', as well as the book, fail to
> properly explain the current behaviour.
The output of "svn help add" doesn't say anything about ignoring files,
and I should think it ought to.
The book documents it in the "Tip" at the end of this section:
<http://svnbook.red-bean.com/nightly/en/svn.advanced.props.special.ignore.html>, and in the "global-ignores" section of <http://svnbook.red-bean.com/nightly/en/svn.advanced.confarea.html#svn.advanced.confarea.opts.config>.
The information ought to be more accessible from the reference section,
which currently says little more than the "svn help ..." output.
> They do not mention the special case where a path is listed as an explicit
> argument. Like the svn_client_add4() docco, they claim that 'svn add'
> would ignore any files which are listed in global ignores or the
> svn:ignores property (I've quoted the relevant bits at the start of this
> thread).
The bit of the book you quoted from is this, which appears just before
the "Tip" I mentioned above:
[[[
As mentioned earlier, the list of file patterns to ignore is also used
by svn add and svn import. Both of these operations involve asking
Subversion to begin managing some set of files and directories. Rather
than force the user to pick and choose which files in a tree she wishes
to start versioning, Subversion uses the ignore patterns--both the
global and the per-directory lists--to determine which files should not
be swept into the version control system as part of a larger recursive
addition or import operation. And here again, you can use the
--no-ignore option to tell Subversion ignore its ignores list and
operate on all the files and directories present.
]]]
Yes, I agree that's misleading by mentioning the per-directory lists, as
that's inapplicable for import and not usually applicable for add.
> Personally, I'm in favour of adjusting the code to match the documentation,
> keeping an old API around that emulates the current behaviour.
> Doing so would keep the feature easy to explain and understand.
I'm ambivalent about changing the behaviour. I see why that behaviour
would be useful as an option, and it would be fine if that was how it
had always been, but do not feel that making it optional would be better
than sticking with the current behaviour.
+1 to improving the help and the book.
- Julian
Received on 2010-02-03 17:02:56 CET