Manual
The intention is that GSync will provide as much of if not all of the same upload and download functionality of RSync, excluding the transport, encoding layers and daemon support of course. So for a full explanation of how to use GSync, you could refer to the RSync man page. However, a demonstration of some use cases are shown below.
I am trying to keep the functionality as close to rsync as possible. The transport for transferring files will be different, i.e. it will never have SSH support, unless only to provide tunnelling for running gsync from behind a firewall (food for thought). But fundamentally, it is backed by Google Drive which is a web based service with a REST API. But semantics for transferring files should be the same as rsync, such as the significance of trailing slashes and how the application behaves when certain options have been specified. The interface should be seamless, allowing people with a knowledge about rsync to just pick up gsync and start using it like it is the same application or an extension of rsync. I myself am an rsync veteran and have used it for back-up for many years, so to find that Google were unable to provide support for transferring files via the rsync protocol was quite a shock. There seemed to be few alternatives that worked with the control and flexibility I required, so I decided to write my own. Initial research into the Google Drive API showed that it provided much of the metadata required to synchronise files with efficiency in a manner close to that of rsync. Some things are yet to be implemented, but features such as checksum verification can be achieved since Google store a checksum of the file in the file metadata. Currently, file attributes and extended attributes are stored in the description field of file metadata, which is a hack I provide to work around the issue of retaining file permissions for the purposes of restoring. If the description is replaced or deleted, file permissions will not be restored.
Authentication is handled by the Google OAuth2 authentication layer. It works in much the same way as any Android application, which has to obtain permission to access features of your device. The difference is that the applications that use oauth2 have to request explicit permission to access your Google services, like GMail, Drive, Calendar and so on. In order to do that, a special permissions token has been generated for this application (which currently is not perpetual so has a limited lifetime; I'll regenerate a new one when the current one runs out). This token is used to request authorisation from you to allow an application using this token to access your Google Drive. However, the token is only permitted when combined with a unique authorisation token that you will get from Google once you have granted permission for GSync to access your drive. This token is then stored in your home directory on the computer you run GSync from, under ~/.gsync. If you remove the ~/.gsync directory, it will remove the cookie and you will need to regenerate a new authentication token. Here is how the process would look:
$ time gsync --owner --group --progress --perms -u -d -r -vi ~/tmp/gsynctest/Debian_Flamme2.jpg drive://unittest/
Warning: Not running as root, file ownership may be ignored
Authorization is required to access your Google Drive.
Navigate to the following URL:
https://accounts.google.com/o/oauth2/auth?scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&response_type=code&client_id=542942405111.apps.googleusercontent.com&access_type=offline
Type in the received code:
If you navigate to the URL provided, you will see something like this:
If you accept, you will see a unique authentication token appear that you must paste into the awaiting prompt. Once done, the cookie is created and authentication need only take place if the cookie is removed or when the token expires.
Note: The authentication message will only appear when data is required to be transferred to or received from your Google Drive. If you do not specify any local files to transfer, the authentication steps shown above will not appear.
$ time gsync --owner --group --progress --perms -u -d -r -vi ~/tmp/gsynctest/Debian_Flamme2.jpg drive://unittest/
Warning: Not running as root, file ownership may be ignored
<f+++++++++ Debian_Flamme2.jpg
73558 0% 35.92KB/s 0:00:02
sent 73558 bytes received 0 bytes 17611.13 bytes/sec
real 0m6.220s user 0m0.492s sys 0m0.064s
$ time gsync --owner --group --progress --perms -u -d -r -vi ~/tmp/gsynctest/Debian_Flamme2.jpg drive://unittest/test.jpg
Warning: Not running as root, file ownership may be ignored
<f+++++++++ test.jpg
73558 0% 23.94KB/s 0:00:03
sent 73558 bytes received 0 bytes 12475.46 bytes/sec
real 0m7.409s user 0m0.560s sys 0m0.096s