doc: fioctl symbolic link to setup git cannot be fixed

Signed-off-by: Camila Macedo <[email protected]>
foundriesio · Nov 2, 2023 · 37ea804 · 37ea804
1 parent b26edc1
commit 37ea804
Showing 1 changed file with 42 additions and 6 deletions.
diff --git a/source/getting-started/install-fioctl/index.rst b/source/getting-started/install-fioctl/index.rst
@@ -213,21 +213,57 @@ 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::
+   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
+   - Configure Git with the necessary credentials:
 
-   * Existing users reconfiguring Git access may need to remove the following lines from ``.gitconfig`` to use ``fioctl configure-git`` utility::
+     .. code-block:: bash
+
+        git config --global credential.https://source.foundries.io.username fio-oauth2
+        git config --global credential.https://source.foundries.io.helper fio
+
+   - 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
+
+   - 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
+
+   Existing users reconfiguring Git access may need to remove the following lines from ``.gitconfig`` to use ``fioctl configure-git`` utility:
+
+   .. code-block:: bash
 
       [http "https://source.foundries.io"]
       extraheader = Authorization: basic <TOKEN>
 
-   * If editing scopes on existing tokens, the user should refresh the local ``fioctl`` credentials with::
+   If editing scopes on existing tokens, the user should refresh the local ``fioctl`` credentials with:
+
+   .. code-block:: bash
 
       fioctl login --refresh-access-token
 
+
 Verify this has succeeded by cloning a repository from your Factory, such as your ``containers.git`` repo.
 Replace ``<factory>`` with your Factory's name: