From 9d1a83962a296c9299d337c3e86cd5709d2b0605 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Szczepanik?= <m.szczepanik@fz-juelich.de>
Date: Wed, 10 Jan 2024 16:25:31 +0100
Subject: [PATCH] Apply one more suggestion from code review

This adds a note to the datalad access documentation, advising users
that cloning from an incorrect datalad-annex URL will not cause an
error, but instead produce an empty repository.

Suggested-by: Adina Wagner <adina.wagner@t-online.de>
---
 docs/source/user/datalad-access.rst | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/docs/source/user/datalad-access.rst b/docs/source/user/datalad-access.rst
index e571047..4c01d71 100644
--- a/docs/source/user/datalad-access.rst
+++ b/docs/source/user/datalad-access.rst
@@ -42,7 +42,19 @@ A full ``datalad clone`` command could then look like this:
 .. code-block::
 
     datalad clone 'datalad-annex::?type=external&externaltype=uncurl&encryption=none&url=file:///tmp/local_dicom_store/dl-Z03/P000624_{{annex_key}}'  my_clone
-    
+
+.. note::
+
+   The clone command will not fail if the ``datalad-annex::`` URL
+   points to a nonexisting target. If you see the following warning:
+
+   .. code-block:: none
+
+      [WARNING] You appear to have cloned an empty repository.
+      [WARNING] Cloned /path/to/my_clone but could not find a branch with commits
+
+   it is likely that the provided URL is mistyped or otherwise not correct.
+
 
 .. note:: The URL is arguably a bit clunky. A convenience short cut can be provided via configuration item ``datalad.clone.url-substitute.<label>`` and a substitution rule based on regular expressions. For example, clone URLs can be shortened to require only an identifier (here, ``file:///data/group/groupname/local_dicom_store``), study ID, and visit ID (``inm-icf/<study-ID>/<visit-ID>``) with the following configuration:
 
@@ -54,6 +66,7 @@ A full ``datalad clone`` command could then look like this:
    You are free to adjust this configuration custom to your needs and preferences.
    Further documentation on it can be found in the `DataLad Docs`_.
 
+
 .. _DataLad Docs: http://docs.datalad.org/en/stable/design/url_substitution.html
 
 Cloning will retrieve a lightweight dataset, which does not (yet)