Support authentication

.travis.yml

@@ -12,7 +12,7 @@ matrix:
 install:
   # newer versions of PyYAML dropped support for Python 3.4
   - if [ $TRAVIS_PYTHON_VERSION == "3.4" ]; then pip install PyYAML==5.2; fi
-  - pip install coverage flake8 flake8-docstrings flake8-import-order pytest PyYAML
+  - pip install appdirs coverage flake8 flake8-docstrings flake8-import-order mock pytest PyYAML
 script:
   - PYTHONPATH=`pwd` pytest -s -v test
 notifications:

README.rst

@@ -138,6 +138,45 @@ 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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The various version control systems supported by vcstool support authenticated access on their own (e.g. SSH public keys, .netrc files, etc.).
+For .tar or .zip repositories, vcstool supports authenticated access 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 exceed that which is required.
+
 How to install vcstool?
 =======================
 

setup.py

@@ -6,7 +6,7 @@
 from setuptools import setup
 from vcstool import __version__
 
-install_requires = ['PyYAML', 'setuptools']
+install_requires = ['appdirs', 'PyYAML', 'setuptools']
 if sys.version_info[0] == 2 and sys.version_info[1] < 7:
     install_requires.append('argparse')
 

stdeb.cfg

@@ -1,6 +1,6 @@
 [DEFAULT]
-Depends: python-argparse, python-setuptools, python-yaml
-Depends3: python3-setuptools, python3-yaml
+Depends: python-appdirs, python-argparse, python-setuptools, python-yaml
+Depends3: python3-appdirs, python3-setuptools, python3-yaml
 Conflicts: python3-vcstool
 Conflicts3: python-vcstool
 Suite: xenial yakkety zesty artful bionic cosmic disco eoan jessie stretch buster