Metadata-Version: 2.0
Name: gcsannex
Version: 0.2
Summary: git-annex external special remote for Google Cloud Storage
Home-page: https://github.com/bgilbert/gcsannex
Author: Benjamin Gilbert
Author-email: bgilbert@backtick.net
License: GPLv3+
Keywords: git-annex gcs Google Cloud Storage
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Plugins
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Topic :: System :: Archiving
Requires-Dist: google-api-python-client
Requires-Dist: PyCrypto

==========================================
git-annex support for Google Cloud Storage
==========================================

This is a git-annex_ external special remote that supports Google Cloud
Storage (GCS).

.. _git-annex: https://git-annex.branchable.com/


Features
========

- Supports Standard, Durable Reduced Availability, and Nearline storage
  classes.
- Accesses Google Cloud Storage via a Google Cloud service account.  Does
  not use the Google Cloud Storage Interoperability API.
- Should support object sizes up to 5 TB.


License
=======

`GNU General Public License, version 3 or later`_.

.. _`GNU General Public License, version 3 or later`: http://www.gnu.org/licenses/gpl-3.0.en.html


Installing
==========

::

  pip install gcsannex


Configuring Google Cloud Storage
================================

1. Log into the `Google Developers Console`_.

2. Create a project if you don't already have one.  Remember its
   project ID.

3. In the project's settings, go to **APIs & auth** > **Credentials**.

4. Click "Create new Client ID", select "Service account", then click
   "Create Client ID".

5. A credentials file will be downloaded to your computer.  You will need
   this file when configuring gcsannex.

.. _`Google Developers Console`: https://console.developers.google.com/


Adding a remote
===============

::

  git annex initremote <remotename> type=external externaltype=gcs encryption={none|shared|pubkey|hybrid} project=<gcs-project-id>

Set the ``GOOGLE_APPLICATION_CREDENTIALS`` environment variable to the
path to your credentials file.  This is only necessary when running
``initremote``; afterward, git-annex will remember your credentials.


Mandatory settings
------------------

``encryption``
  See the `git-annex encryption documentation`_.

``project``
  Your project ID from the Google developer console.

.. _`git-annex encryption documentation`: http://git-annex.branchable.com/encryption/


Optional settings
-----------------

``bucket``
  The bucket name, which must be globally unique within GCS.  The default
  name is based on the remote name and UUID.

``chunk``
  Enable chunking_.

``embedcreds``
  Set to ``yes`` to commit the login credentials to the Git repository
  so other clones can read them.  When using GPG encryption, the default is
  ``yes`` and the credentials are stored encrypted.  Otherwise, the default
  is ``no``; if set to ``yes``, anyone with access to the repo can also
  access the GCS bucket.

``fileprefix``
  A string, such as ``mydata/``, to be prepended to the name of each object.
  This allows a bucket to be shared by multiple remotes.

``location``
  The physical location for the data.  Can be any of the `location strings`_
  supported by GCS, such as ``ASIA``, ``EU``, or ``US``.  Defaults to ``US``.

``public``
  If ``yes``, newly-uploaded objects are made publicly readable.  Defaults
  to ``no``.

``readonly``
  If set to ``true`` when enabling an existing ``public`` remote, files
  can be retrieved without GCS credentials and without gcsannex installed.
  Requires development version of git-annex.

``storageclass``
  A `storage class`_ supported by GCS, such as ``STANDARD``,
  ``DURABLE_REDUCED_AVAILABILITY``, or ``NEARLINE``.  Defaults to
  ``STANDARD``.

.. _chunking: http://git-annex.branchable.com/chunking/
.. _`location strings`: https://cloud.google.com/storage/docs/bucket-locations
.. _`storage class`: https://cloud.google.com/storage/docs/storage-classes

Release notes
=============

Version 0.2
-----------

- Time out stuck requests
- Retry after more types of errors
- Permit encrypted public remotes
- Support showing public URLs in ``git annex whereis``
- Improve compatibility with git-annex < 5.20141219
- Properly accept implicit ``encryption=hybrid``

Version 0.1
-----------

- Initial release


