Skip to content

guide.md

Latest commit

 

History

History
168 lines (124 loc) · 11.7 KB

guide.md

File metadata and controls

168 lines (124 loc) · 11.7 KB

Table of contents


Quickstart

Google Cloud project setup

To use CLID, you need to create a Google Cloud project. Follow the step-by-step tutorial to set it up.

  1. Open the Google Cloud Console web page and log in.
  2. On the top-left, click on Select project and create a new project.
  3. Give the project a name (any name will do) and click Create
  4. Go to the OAuth Consent screen, select your project and set the user type to External.
  5. Fill only the necessary fields (App name, support email and developer email). The last two can be the same email you used to log in Google Cloud. After filling the information, skip until you reach Test Users.
  6. In Test Users, add the emails you want to use with CLID (you can specify one or more emails). After that, click Save and Continue.
  7. Open the Google Drive API page, select the project you've created and activate the API.
  8. Now, go to the Credentials page and create a new OAauth Client credential.
  9. In Application type, choose Desktop app, give it a name and click Create.
  10. In the pop-up window that will open, download the JSON file.
  11. The JSON file will be named client_secrets_(longStringHere).json. Rename it to credentials.json.
  12. Move the credentials.json file to the CLID folder (Same place where CLID.py is located) after doing the installation steps mentioned below, for your respective operating system.

Windows installation

  1. Make sure to have Python 3.10+ version installed.
  2. Clone/download the repository.
  3. Install virtualenv using pip install virtualenv.
  4. Navigate to the project folder using cd path/to/[CLID_folder].
  5. Create a new virtual environment in the project folder, named CLID_env, using virtualenv CLID_env.
  6. Activate the virtual environment by navigating to the Scripts folder using cd CLID_env/Scripts. After that, type activate.
  7. After activating the virtual environment, install the required dependencies using pip install -r requirements.txt.
  8. Open CLID.py in the editor, copy the Windows shebang and paste it on the first line of the code.
  9. You can then run CLID in the terminal using only CLID.py or directly clicking on the CLID.py file or a shortcut.

Linux installation

  1. Make sure to have Python 3.10+ version installed.
  2. Clone/download the repository.
  3. Install virtualenv using pip install virtualenv.
  4. Navigate to the project folder using cd path/to/[CLID_folder].
  5. Create a new virtual environment in the project folder, named CLID_env, using virtualenv CLID_env.
  6. Activate the virtual environment using source CLID_env/bin/activate.
  7. After activating the virtual environment, install the required dependencies using pip install -r requirements.txt.
  8. Open CLID.py in the code editor, copy the Linux shebang and paste it on the first line of the code.
  9. Make CLID.py executable by using chmod u+x CLID.py.
  10. You can then run CLID in the terminal using ./CLID.py.

First Run

The first time you run CLID, a authentication flow will start, and the browser will open. After that, choose the account in which you want to access its Google Drive with CLID (and remember, only accounts that are Test Users will work. Refer to step 6 of Google Cloud project setup for more information).

After that, a token.json file will be generated from credentials.json. If you want to switch accounts, simply delete token.json, run CLID and choose another (test user) account in the authentication flow.

Moving the CLID folder

Be careful when moving the CLID folder around your system after you've created CLID_env. virtualenv created folders will break when being moved, making CLID stop working.

If you need to move the CLID folder to another place in your system, delete CLID_env, move the CLID folder and redo the virtual environment creation steps, mentioned above, for your operating system.

User guide

Downloading

Downloading a file/folder is really easy:

  1. From the menu, type D to enter the download mode.
  2. Search for the file you want by typing its name, or type list to get a list of the files/folders present in your Drive.
  3. Choose the number of the file you want to download
  4. Choose a download directory...

And that's it! If the file is compressed, you'll get a option to extract it after the download. Supported formats for extraction are .zip, .tar.gz and .tar.

Although the download process is simple, there are some important things you need to keep in mind:

Google Workspace file/folder download

In CLID, it's possible to download either a single file or a folder. Note that, when downloading a folder, it's not going to get zipped beforehand. CLID will instead 'copy' your Google Drive folder structure, creating folders in your local system when needed, and downloading the files inside said folders.

Now, about Google Workspace files. When downloading a Google Workspace file (Docs, Presentation, etc), you'll be able to choose to what format you want the export the file before download. On the other hand, when downloading a folder that has a Google workspace file(s), CLID will choose a export format automatically, and if the file is of an unsupported type, it will skip it.

In conclusion, trying to download a unsupported file will cancel the download operation (for single file downloads), or skip the file (when downloading folders). You can refer to the table below for information about what export formats are supported for each download mode (single file or folder).

Google Workspace File Single file download Folder download
Google Documents MS Word, HTML, Plain Text or PDF MS Word
Google Slides (Presentation) MS PowerPoint or PDF MS PowerPoint
Google Sheets MS Excel, CSV or PDF MS Excel
Google Jamboard PDF PDF
Google Drawing PNG, JPEG, SVG or PDF PNG
Google App Scripts JSON JSON
Google Sites ❌ Not supported ❌ ❌ Not supported ❌
Google Forms ❌ Not supported ❌ ❌ Not supported ❌
Google My Maps ❌ Not supported ❌ ❌ Not supported ❌

Uploading

Uploading a file with CLID is also very simple:

  1. From the menu, type C to enter the upload mode.
  2. Specify the absolute path of the file you want to upload.

After the two steps mentioned above, the upload process will begin. If the file is a directory (folder), CLID will automatically compress the directory before uploading to Google Drive (you can use a 3rd party app inside Google Drive to unzip the file if you want).

CLID also checks if the file is already present in your Drive, and if it is, it gives you the option to replace the file or to keep both files, renaming the file you're uploading to something like file(1).zip.

Calculating folder size

CLID can also calculate the folder size of a Drive folder. It does that by iterating over all files present in the folder, getting their size and adding to a total. At the end of the operation, you'll get a summary with information about the folder's name, size, total number of files, folders, Google Workspace files and unsupported files.

This process can take a while for folders with a lot of subfolders inside. The more subfolders a folder has, the longer it will take to calculate its size.

Important: Do note that this number is an approximation, as depending of the contents of the folder, the final size may be different after downloading to your local system. This happens when dealing with Google Workspace files, mainly because of file size differences, depending of which format the file was exported to (some export format are lighter/heavier than others).

Settings and preferences

CLID has a settings.json file that lets the user change how CLID behaves. For any change you made in settings.json to take effect, you'll need to restart CLID. Here's a rundown of what each setting does:

download_directory (string | null)

Allows the user to specify a download directory for all the files/folders downloaded with CLID. If "download_directory": null, CLID will ask for a download directory every time you download a file.

Example: "download_directory": "C:\\Users\\Gustavo\\Downloads"

CLID will skip the download directory prompt, and all files/folders downloaded with CLID will end up in the Downloads folder. Note that the specified path must be an absolute path.

By default, this setting value is null.

upload_path (string | null)

Almost the same thing as download_directory, but it regards file uploading. Specify a absolute path of a file you want to upload, and CLID will skip the prompt for a file path when in upload mode. Really useful if you upload the same file/folder to Google Drive a lot of times. If "upload_path": null, CLID will ask for a file path every time you want to upload a file.

Example: "upload_path": "C:\\Users\\Gustavo\\file.txt"

By default, this setting value is null.

IMPORTANT: For both download_directory and upload_path, remember to use double backslashes ( \\ ) or single foward slash ( / ) in the file/directory path. This is common issue in Windows because when copying the path of a file or directory, it is usually separated using a single backslash ( \ ), which is not supported by JSON.

shared_with_me (bool)

Modifies how CLID sees and lists your Google Drive files.

  • false : CLID will search/list only files and folders created/owned by the user when downloading or calculating a folder size.
  • true : CLID will search/list files and folders created/owned by the user, as well as files/folders shared with the user, when downloading or calculating a folder size.

By default, this setting value is false.

preferred_compression_format (string)

Changes the preferred compression format when compressing folders for upload. The supported formats are:

  • ".zip"
  • ".tar.gz"

Example: "preferred_compression": ".tar.gz"

If you plan to use CLID to upload/download files that will be used between Windows and Linux systems, it's best to use .tar.gz format, as it can help avoid character encoding problems that can occur when using .zip.

If you plan to use CLID only on Windows systems, then .zip should be enough. If problems with file names appear, try switching to .tar.gz.

By default, this setting value is ".tar.gz".