[darcs-users] Boring files

Tue Dec 28 15:27:02 UTC 2021

You can find more readable version of this text here:
https://hub.darcs.net/ki11men0w/profile/browse/presentations/darcs-boring-files

PROBLEMS WITH USING [boring|binaries] FILES IN _DARCS_

Recently, I have started actively using _darcs_ in my work. Before that,
I worked only with _git_ for many years and during this time I got used
to some patterns of working with _VCS_.

I would like to discuss some points that seem illogical or inconvenient
to me when working with _darcs_ with _boring_ and _binaries_ files.
Below I will write only about _boring_ files, but everyting also applies
to _binaries_ files.

In _darcs_ there are three ways to configure which files to be ignored:

1.  ~/.darcs/boring

    A configuration file globally for the user specifying which files
    should be ignored in all his repositories.

    THIS IS A USER-LEVEL SETTING.

2.  _darcs/prefs/boring

    The default configuration file that specifies the ignore rules for a
    particulat clone of the repository. It is specific and private for
    each clone of the repository. It is not under version control and is
    not copied by the clone command, and so is not shared between clones
    of the repository.

    THIS IS A CLONE-LEVEL SETTING.

3.  The file specified using `darcs setpref boringfile ...`

    If set, it is used instead of _darcs/prefs/boring. Usually a file
    set in this way is put under version control so that it can be
    shared among different developers.

    THIS IS A REPOSITORY-LEVEL SETTING.

In the world of git, I am used to the fact that when creating a
repository in the repository itself, no ignores are configured
automatically. I am used to the fact that the ignoring of files
resulting from the work of the tools used by the programmer during
development should be carried out at the user level, not the repository
level. Different programmers use different tools and taking into account
all their preferences at the repository level very quickly leads to
cluttering of the boring file. I am used to the fact that the file with
the ignore settings at the repository level should contain only what
does not make sense to take into account in the user level settings,
because it is specific for this repository. I'm used to the fact that
boring configuration at the repository level is rather a rare exception:
all ignores are almost always configured either at the user level or at
the clone level.

I do not insist that everyone should adhere to the described approach.
But it seems convenient to me and I would like to stick to it. But it
turned out that _darcs_ is not flexible enough for this. There are two
main points that I would like to change in _darcs_ in order to be able
to work with boring files in the way I'm used to.

Problem #1: in the newly created repositories, _darcs/prefs/boring file is always filled with templates.

The init, clone and convert import commands always create a
template-filled file _darcs/prefs/boring in the new repository.

This turned out to be an unpleasant surprise for me. The default
template leads to ignoring files that are important for my work, which
in turn led to frequent errors when the necessary files were not under
version control. I cleaned up the _darcs/prefs/boring file in my
repository, but when cloning it was filled with the default template
again. In the end, I figured out that permanent cleaning of this file
when executing the init and clone commands can be achieved by placing
the following lines in the ~.darcs/defaults file:

    clone posthook echo > _darcs/prefs/boring
    initialize posthook echo > _darcs/prefs/boring

I understand that filling with template is done specifically to make
life easier for those who are starting to learn _haskell_, but for
everyone else it's more of a disservice. This behavior is not described
in the documentation for the init|clone commands and there is no way to
understand what will happen exactly until an error is made.

It seems to me it would be convenient to have a command line option that
allows you to create a file _darcs/prefs/boring empty (without
templates) when executing these commands. This will allow, firstly, to
explicitly learn about this feature from the help, and, secondly, to
simplify the configuration in the ~.darcs/defaults file.

Decision

I implemented this feature in this patch:
https://hub.darcs.net/ki11men0w/darcs-screened/patch/24e79fb194b4caa073f43dc6707cceba500c29fc.
The corresponding command line options are called
--[with|no]-prefs-templates. If none of these options are set, or the
--with-prefs-templates option is set, then _darcs_ behaves as before. To disable
the filling of the file _darcs/prefs/[boring|binaries] for all cases, you can
add to ~.darcs/defaults the line:

    ALL no-prefs-templates

Problem #2: ignoring the _darcs/prefs/boring file after setpref

As I wrote above, the _darcs/prefs/boring file allows you to perform
ignore settings at the repository clone level. This is exactly what is
needed in most special cases, which it does not make sense to take into
account at the user level in ~/.darcs/boring. The programmer can safely
edit this file as it suits him without thinking about the consequences
for other development participants, because this file is not shared
between different repository clones.

But after explicitly installing the boring file at the repository level
(shared by all repository clones and, accordingly, by all development
participants) using the command:

    darcs setpref boringfile ...

the _darcs/prefs/boring file now ceases to be taken into account
(completely ignored). Now the programmer has no way to set borings that
do not make sense for other development participants (or even in other
clones of his repository). In the user's global configuration file
specific repository instance only as a temporary crutch. You can add
these templates to the file specified via setpref and not write these
changes to patches. But this is inconvenient, because the command
whatsnew|record and the like will constantly suggest these changes for
saving, the command rebase unsuspend will require revert of these
changes before its execution, etc. Adding your templates to the file
specified by setrpef and saving this change in one of the patches is
also a bad idea - it can create problems for other developers if this
patch will be published.

It turns out that after explicitly specifying the boring file with the
setpref command, the developer has no good options for setting borings
at the repository clone level.

It seems to me that the files _darcs/prefs/boring and the file installed
via setpref have a different purpose: the first sets ignoring at the
CLONE level, and the second - at the REPOSITORY level. And therefore,
these configuration files should not be interchangeable, but should
complement each other. Then at each of the configuration levels: user,
repository and repository clone, its own independent configuration will
always be possible. And the full configuration will be applied, taking
into account the settings at all three levels.

To implement this, it is enough that the file _darcs/prefs/boring is
always taken into account, regardless of whether the ignore file is
specified by the setpref command or not.

Decision

I implemented this feature in this patch:
https://hub.darcs.net/ki11men0w/darcs-screened/patch/9b336cbb222b26a2122194e1ece08dc572cfc57c.

Unfortunately, I failed to make sure that the new behavior could be
enabled with a command-line option and that everything would work out as
before by default (more precisely, I did it, but the change turned out
to be extremely ugly and affected a lot of code, so it would hardly be
accepted). But all the possible negative effect of this change will be
reduced only to the fact that in repositories where the ignore file is
explicitly set with the setpref command, files that were not ignored
before may begin to be ignored: these are the files that fit the
templates specified in _darcs/prefs/boring, but do not fit the templates
from the file specified via setpref. It seems to me very unlikely that
this problem will become relevant for someone.

Conclusion

Maybe I'm wrong about something, maybe I don't see the obvious things. I
will be glad to receive feedback from the respected community.

I plan to send these patches to http://darcs.net/screened. Patches have no
dependencies on each other, so it will be two separate patchsets. Before that, I
had not participated in the development of _darcs_ and therefore decided to
first discuss the possibility of including these patches in the main
repository. Any comments are welcome.

-- 
Maksim Golubev <maksim.golubev72 at gmail.com>