Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Disambiguations in the configuration sections #627

Merged
merged 1 commit into from
Dec 10, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion docs/basics/101-122-config.rst
Original file line number Diff line number Diff line change
Expand Up @@ -322,7 +322,7 @@ editor configuration, should they have included one in their config file.
Instead, upon a :command:`datalad clone`, a new config file will be created.


This means, however, that configurations that should "stick" to a dataset
This means, however, that configurations that should "stick" to a dataset [#f5]_
need to be defined in different files -- files that are version controlled.
The next section will talk about them.

Expand Down Expand Up @@ -362,3 +362,8 @@ The next section will talk about them.

.. [#f4] A UUID is a universally unique identifier -- a 128-bit number
that unambiguously identifies information.

.. [#f5] Please note that not all configurations can be written to files other than ``.git/config``.
Some of the files introduced in the next section will not be queried by Git, and in principle, it is a good thing that one can not share arbitrary configurations together with a dataset, as this could be a potential security threat.
In those cases where you need dataset clones to inherit certain non-sticky configurations, it is advised to write a custom procedure and distribute it together with the dataset.
The next two sections contain concrete usecases and tutorials.
4 changes: 2 additions & 2 deletions docs/basics/101-123-config2.rst
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ This file lies right in the root of your superdataset:

.. windowsworkarounds:: Your file contents are slightly different

Windows users that did not use the custom :term:`git-annex` installer from ` http://datasets.datalad.org/datalad/packages/windows/ <http://datasets.datalad.org/datalad/packages/windows/ >`_ had to modify the ``.gitattributes`` file at the start of the Basics.
Windows users that did not use the custom :term:`git-annex` installer from `http://datasets.datalad.org/datalad/packages/windows/ <http://datasets.datalad.org/datalad/packages/windows/>`_ had to modify the ``.gitattributes`` file at the start of the Basics.
Instead of a line that contains "``mimencoding``", There should be the following two lines::

*.txt annex.largefiles=nothing
Expand Down Expand Up @@ -202,7 +202,7 @@ will take precedence over configurations that can be distributed with a dataset.
Otherwise, dataset updates with :command:`datalad update` (or, for Git-users,
:command:`git pull`) could suddenly and unintentionally alter local DataLad
behavior that was specifically configured.

Also, :term:`Git` and :term:`git-annex` will not query this file for configurations, so please store only sticky options that are specific to DataLad (i.e., under the ``datalad.*`` namespace) in it.

Writing to configuration files other than ``.git/config``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand Down
4 changes: 2 additions & 2 deletions docs/basics/101-124-procedures.rst
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ nothing more than a simple script that

.. windowsworkarounds:: Why this configuration does not work for Windows users

If you're on a **Windows 10** machine with a **native** (i.e., non :term:`WSL` based installation) of DataLad and its underlying software, the ``text2git`` configuration will lead to errors upon a :command:`datalad save`.
If you're on a **Windows 10** machine with a **native** (i.e., non :term:`WSL` based installation) of DataLad and did **not** use the custom :term:`git-annex` installer from `http://datasets.datalad.org/datalad/packages/windows/ <http://datasets.datalad.org/datalad/packages/windows/>`_ at the start of the Basics, the ``text2git`` configuration will lead to errors upon a :command:`datalad save`.
This is because MagicMime (used in ``mimeencoding=binary`` to determine the file type of any given file by searching for `magic numbers <https://en.wikipedia.org/wiki/List_of_file_signatures>`_) is not natively available on Windows.

This particular procedure lives in a script called
Expand Down Expand Up @@ -188,7 +188,7 @@ was applied.
Procedures can come with DataLad or its extensions, but anyone can
write their own ones in addition, and deploy them on individual machines,
or ship them within DataLad datasets. This allows to
automate routine configurations or tasks in a dataset.
automate routine configurations or tasks in a dataset, or share configurations that would otherwise not "stick" to the dataset.
Some general rules for creating a custom procedure are outlined
below:

Expand Down
4 changes: 2 additions & 2 deletions docs/basics/101-125-summary.rst
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ your horizon about configurations of datasets:
- Configurations exist at different scopes and for different tools. Each
of such configuration scopes exists in an individual file, on a *system-wide*,
*global* (user-specific) or *local* (repository specific) level. In addition
to Git's *local* scope in ``.git/config``, DataLad introduces configurations within
to Git's *local* scope in ``.git/config``, DataLad introduces its own configurations within
``.datalad/config`` that apply to a specific dataset, but are committed and
therefore distributed. More specialized scopes take precedence over more global scopes.

Expand All @@ -35,7 +35,7 @@ your horizon about configurations of datasets:
and which are stored in Git.

- DataLad's ``run-procedure``\s offer an easy and fast alternative to DIY
configurations, structuring, or processing of the dataset.
configurations, structuring, or processing of the dataset, and offer means to share or ship configurations together with a dataset.
They can be applied already at creation of a dataset with ``datalad create -c <procedure>``,
or executed later with a :command:`datalad run-procedure` command.

Expand Down