doc: fioctl symbolic link to setup git cannot be fixed

Signed-off-by: Camila Macedo <[email protected]>
foundriesio · Nov 6, 2023 · ff160cc · ff160cc
1 parent b26edc1
commit ff160cc
Show file tree

Hide file tree

Showing 2 changed files with 43 additions and 5 deletions.
diff --git a/source/getting-started/install-fioctl/index.rst b/source/getting-started/install-fioctl/index.rst
@@ -213,11 +213,7 @@ Run the following command to add the relevant entries to the Git configuration:
    This is because it needs to have privileges to create a symlink in the same directory as where ``git`` is located.
 
 .. warning::
-   * If for some reason the command fails with an error, the following manual steps can be taken to get the exact same result::
-
-      git config --global credential.https://source.foundries.io.username fio-oauth2
-      git config --global credential.https://source.foundries.io.helper fio
-      ln -s /usr/local/bin/fioctl /usr/bin/git-credential-fio
+   * If for some reason the command ``sudo fioctl configure-git`` fails with an error, manual steps can be taken to get the exact same result. For comprehensive instructions, please see the :ref:`Fioctl™ Errors <ref-ts-errors>` section.
 
    * Existing users reconfiguring Git access may need to remove the following lines from ``.gitconfig`` to use ``fioctl configure-git`` utility::
 

diff --git a/source/user-guide/troubleshooting/troubleshooting.rst b/source/user-guide/troubleshooting/troubleshooting.rst
@@ -10,6 +10,48 @@ This page covers a variety of topics falling under addressing specific :ref:`err
 Errors and Solutions
 ---------------------
 
+Fioctl™ Errors
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If for some reason the command ``sudo fioctl configure-git`` fails with an error, the following manual steps can be
+taken to get the exact same result:
+
+1. Configure Git with the necessary credentials:
+
+ .. code-block:: bash
+
+    git config --global credential.https://source.foundries.io.username fio-oauth2
+    git config --global credential.https://source.foundries.io.helper fio
+
+2. Create the symbolic link manually. The correct path will be displayed in the `Fioctl` error message and may vary depending on your operating system and Git configuration environment.
+
+ **Example**:
+
+ .. code-block:: bash
+
+    $ sudo fioctl configure-git
+    Symlinking /usr/local/bin/fioctl to /opt/homebrew/bin/git-credential-fio
+    ERROR: symlink /usr/local/bin/fioctl /opt/homebrew/bin/git-credential-fio: file exists
+
+ In the above example, the symbolic link command would be:
+
+ .. code-block:: bash
+
+    sudo ln -sf /usr/local/bin/fioctl /usr/local/bin/git-credential-fio
+
+ However, for Linux environments, it is usually:
+
+ .. code-block:: bash
+
+    sudo ln -s /usr/local/bin/fioctl /usr/bin/git-credential-fio
+
+3. Configure Git to use the correct `git-credential-fio` helper by specifying its path:
+
+ .. code-block:: bash
+
+    git config --global credential.helper /path/to/symlinking/git-credential-fio
+
+
 Aktualizr-Lite Common Reports
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^