From 8b402e47e886ba405996248259b37820b864c1b4 Mon Sep 17 00:00:00 2001
From: Kyle Fazzari <kyle@canonical.com>
Date: Tue, 26 May 2020 13:25:58 -0700
Subject: [PATCH] Document authentication behavior in README

Signed-off-by: Kyle Fazzari <kyle@canonical.com>
---
 README.rst                  | 42 +++++++++++++++++++++++++++++++++++++
 vcstool/clients/vcs_base.py | 12 ++++++++---
 2 files changed, 51 insertions(+), 3 deletions(-)

diff --git a/README.rst b/README.rst
index a068eb51..0d209fbc 100644
--- a/README.rst
+++ b/README.rst
@@ -138,6 +138,48 @@ The set of repositories to operate on can optionally be restricted by the type:
 If the command should work on multiple repositories make sure to pass only generic arguments which work for all of these repository types.
 
 
+Access repositories that require authentication
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Vcstool supports authenticated access to repositories by parsing files with a netrc-like format.
+It will first look for login information in the ~/.netrc file, used by ftp, git, and similar programs if it exists.
+If it doesn't exist (or doesn't contain login infomation for the URL in question), it moves to vcstool-specific locations.
+In these locations vcstool will look for credentials in either an `auth.conf` file, or .conf files inside an `auth.conf.d` directory.
+These locations are (in order of precedence):
+
+1. User config directory.
+   - On Linux, abides by XDG spec: `~/.config/vcstool/`
+   - On macOS: `~/Library/Application Support/vcstool/`
+   - On Windows: `C:\Users\<username>\AppData\Local\vcstool\vcstool\`
+2. Site config directory.
+   - On Linux: `vcstool/` subdirectory in any directory within `$XDG_CONFIG_DIRS`, or `/etc/xdg/vcstool/` if unset
+   - On macOS: `/Library/Application Support/vcstool/`
+   - On Windows: `C:\ProgramData\vcstool\vcstool\`
+
+The netrc-like format consists of a few different tokens separated by whitespace (spaces, tabs, or newlines):
+
+- `machine <name>`: Credentials are retrieved by matching the repository URL to this token
+- `login <name>`: Login username
+- `password <string>`: Login password
+
+For example, to access private github repositories:
+
+```
+machine github.com
+login mylogin
+password myaccesstoken
+```
+
+Accessing private gitlab repositories looks similar, although no `login` is required:
+
+```
+machine gitlab.com
+password myaccesstoken
+```
+
+A word of caution: these files are not encrypted.
+Ensure that their permissions do not exeed that which is required.
+
 How to install vcstool?
 =======================
 
diff --git a/vcstool/clients/vcs_base.py b/vcstool/clients/vcs_base.py
index 2af3751c..ae36727b 100644
--- a/vcstool/clients/vcs_base.py
+++ b/vcstool/clients/vcs_base.py
@@ -222,9 +222,15 @@ def _credentials_for_machine(machine):
     if credentials:
         return credentials
 
-    # Finally, check the system-wide auth directory for vcstool
-    return _credentials_for_machine_in_dir(
-        appdirs.site_config_dir(_APPDIRS_PROJECT_NAME), machine)
+    # Finally, check the system-wide auth directories for vcstool, in order
+    auth_path = appdirs.site_config_dir(_APPDIRS_PROJECT_NAME, multipath=True)
+    for site_config_dir in auth_path.split(':'):
+        credentials = _credentials_for_machine_in_dir(
+            site_config_dir, machine)
+        if credentials:
+            return credentials
+
+    return None
 
 
 def _credentials_for_machine_in_dir(directory, machine):