Subject: Re: bug#37189: 25.4.1: vc-hg-ignore implementation is missing

From: Wolfgang Scherer <[email-masked]>
Date: Wed, 12 Feb 2020 18:23:32 +0100

Hi Eli,

I have refactored the API change request according to the latest
discussion. I assume, that the "file path" use case must be
implemented anyway, correct?

I have changed the code, such that the user visible changes are
absolutely minimized. Only one change remains, which never worked
before anyway.

I have also attached a complete sequence diagram, with annotations to
show, that it is not possible to determine the correct ignore file in
a subdirectory with an escaped pattern in all cases.

### API change

Function func:vc-ignore is modified to handle both the "pattern" and the
"file path" use cases.

-   The parameter FILE of *cv-ignore* is renamed to PATTERN-OR-FILE to
    clarify its dual purpose.

-   The additional optional parameter is-file is introduced to determine
    how the PATTERN-OR-FILE argument should be treated. If it is nil
    (the default) the behavior is unchanged. Otherwise, a file path is
    expected, which is transformed to fit the ignore file location and
    then escaped according to the VC pattern syntax.

-   The documenation string of *vc-ignore* is clarified to avoid
    possible misconceptions,like a file somehow being equivalent to a
    wildcard, or that glob(7) patterns are the only type of patterns for
    version control systems.

-   For the "file path" use case, users have come to expect that they
    can mark several file in *vc-dir-mode* and *dired-mode* to perform
    VC operations on that fileset. This is implemented in function
    *vc-ignore-fileset*. in *dired-mode* the user is prompted before
    making any changes (similar to a delete operation).

-   The new function *vc-ignore-pattern* is an alias for *vc-ignore* to
    allow for a clear and unambiguous documentation string that does not
    mix use cases.

-   The new function *vc-ignore-file*, when called interactively, either
    operates on the current fileset in *vc-dir-mode* and *dired-mode* or
    prompts for a file to ignore.

-   The function *vc-dir-ignore* is modified to call
    *vc-ignore-pattern* interactively. After processing, a message is
    displayed in the echo area with a hint to press "F" for ignoring files.

### Proposed keyboard shortcuts

`C-x v F` => *vc-ignore-file*\
`C-x v G` => *vc-ignore-pattern* ; functionality unchanged

in *vc-dir-mode*:

`F` => *vc-ignore-file*\
`G` => *vc-dir-ignore* ; functionality was broken

### User-visible changes

The only user-visible change in the current features is the keyboard
shortcut "G" in *vc-dir-mode*. It does no longer write an invalid
absolute file path into the ignore file, but prompts for a pattern
instead. An additional hint to press "F" for ignoring files is displayed
afterwards.

The only new feature is *vc-ignore-file* for ignoring an unescaped |file path|.

Greetings, Wolfgang