Drive Backup Tool — Help & FAQ

Help

This page explains how to use the Drive Backup Tool: create backup profiles, run backups, clone folders, relink spreadsheets inside clones, and keep the newest N backups automatically.

What this tool is best at: long-running Drive operations (clone + relink) with retries, detailed logs, and automatic retention — the stuff that often times out in Apps Script.

Reminder: backups are copies. If you need true “undo”, keep enough snapshots (retention) and use restore workflows (or manual copy-back) when needed.

Quick start

Sign in with Google and grant access (scopes explained below).
Create a Backup Profile:
- Source folder (the live folder you want to snapshot)
- Backup root folder (where dated backups are created)
- Options: Relink spreadsheets, Retention, and any naming settings
Click Run on the profile.
Watch live logs and wait for a final summary (files cloned, sheets relinked, any failures).

Example output folder:
Backup Root/
  2025-12-17_0930/
    Phase 3/   (cloned snapshot)

Key concepts

Concept	What it means	Why it matters
Backup Profile	A saved configuration: source folder → backup root folder (+ options).	Makes runs repeatable and schedulable.
Snapshot	A dated folder created under your backup root on each run.	Gives point-in-time restore ability.
Clone	Copies the entire folder tree (structure + files) into the snapshot.	This is the “heavy” part—can take minutes or hours on large trees.
Relink	Updates spreadsheets inside the clone so references point where you expect.	Prevents clones from accidentally still pulling data from “live” sources.
Retention	Keep the newest N snapshots and delete older ones.	Stops backups growing forever while preserving recent restore points.
Job	A single run (manual or scheduled) with logs + results.	Everything is trackable, auditable, and retryable.

Backup profiles

A profile is the “recipe” for backups. Typical fields:

Field	Description	Tips
Profile name	Friendly label used in the UI and job history.	Use something like `Backup of live PHASE 3`.
Source folder	The folder to clone each run.	Use the folder ID or full Drive URL.
Backup root	Where snapshots are created.	Keep this separate from your live working folders.
Snapshot naming	How dated folders are named (timestamp format).	Use sortable timestamps like `YYYY-MM-DD_HHmm`.
Relink mode	Whether to rewrite spreadsheet links inside the clone.	Enable if your clones contain sheets that reference other sheets.
Retention	How many recent snapshots to keep.	Start with 5–10; increase if you need longer rollback windows.

Running jobs & live logs

Each run creates a job with a unique ID and a live log stream.

Common job phases

Create snapshot folder (timestamp folder under backup root)
Clone folder tree (copy folders + files)
Relink spreadsheets (if enabled)
Retention cleanup (delete older snapshots)
Summary (counts + any failures)

Example log lines you might see

Starting backup 'Backup of live PHASE 3'
Creating timestamp folder: 2025-12-17_0930
Cloning source folder…
cloneFolder starting
Relink: scanning spreadsheets…
Relink: updated 137 references
Retention: keeping newest 5 backups
Backup completed.

If a job looks “stuck”: it’s usually waiting on Google Drive/Sheets API rate limits. The retry/backoff system will keep it moving—check logs for “retry/backoff” lines.

Relinking spreadsheets

Relinking prevents cloned spreadsheets from still pointing at the originals (or at old backup copies) when formulas or hyperlinks reference other files.

What relink typically targets

IMPORTRANGE source spreadsheet IDs
Drive URLs embedded in formulas
Hyperlinks that point at “live” files (if your relinker supports them)

What relink does not do

It won’t fix broken links to files that weren’t included in the clone.
It won’t guess intent if multiple possible targets exist (it follows your mapping rules).

Best practice: keep related spreadsheets together under the source folder so the clone contains everything relink needs.

Retention

Retention deletes older snapshots after a successful run (or at the end of a run, depending on configuration).

Keep newest N is the simplest approach.
If you need “monthly” or “pinned” backups, add a pin/lock feature (optional enhancement) so important snapshots never get deleted.

Suggested retention defaults

Personal projects: 5–10
Active production workflows: 10–20
High-risk changes periods: temporarily raise to 30+

Scheduling

Scheduling runs profiles automatically. The exact options depend on your UI, but the common model is:

Pick a timezone (recommend: keep it consistent for all profiles)
Set frequency (daily/weekly) and time
Pause/resume schedules without deleting the profile

Tip: schedule large backups outside busy hours to reduce API contention and make troubleshooting easier.

Permissions & scopes

This tool needs Google permissions to read your source folder and write to your backup root. Typical requirements include:

Drive access to list/read/copy files
Sheets access to read/update formulas during relinking

Least privilege: request only the scopes you actually use. If you can use Drive “file” scope for user-selected files/folders, that can reduce review friction (but may limit functionality).

If you ever revoke access, scheduled jobs will fail until re-authorized.

Best practices

Use a dedicated backup root (don’t back up into the same live folder tree).
Keep related sheets together so relinking can map correctly.
Start with a manual run before enabling schedule.
Watch the first run and keep the job summary as a baseline.
Increase retention temporarily when you’re making risky structural changes.

FAQ

How long will a backup take?

It depends on folder size, number of files, and Google API rate limits. Large Drive trees can take minutes to hours. Check the live logs for progress and backoff messages.

Will this back up permissions/sharing settings?

Usually cloning copies the file content and structure; whether permissions are preserved depends on the copy strategy. If you need permission mirroring, treat it as a dedicated feature (and test on a small folder first).

What happens if the job fails halfway through?

The system retries transient errors automatically. If it still fails, you’ll see a clear error in the job summary. Partial snapshots may remain in the backup root so you can inspect what completed.

Can I restore a backup?

Yes—restoring is typically “copy back” from a snapshot to a target location. Many users restore a single file/folder manually; a one-click restore flow can be added if needed.

Does relink change my live files?

No. Relink should only operate on the spreadsheets inside the cloned snapshot folder.

Why do I see “Cannot relink” for some sheets?

Common causes: the referenced file wasn’t cloned, the formula format is unsupported, or the link target can’t be uniquely identified. The log should show the exact reference it couldn’t map.

Troubleshooting

Issue	What to check
Job stuck / no new logs	Leave it for a bit (API backoff can be quiet). Refresh the Jobs page. Check for rate-limit messages earlier in the log.
Auth errors	Re-auth with Google. Confirm the source and backup folders are still accessible to the same account.
Clone incomplete	Check whether specific files failed due to permissions, file type restrictions, or API errors. Retry the job.
Relink didn’t change anything	Confirm relink is enabled on the profile. Confirm the clone contains multiple spreadsheets with references that actually need rewriting.
Retention deleted something I wanted	Increase N, or add a “pin snapshot” feature. For now, move important snapshots out of the retention-managed folder.

When reporting a bug: include the job ID, a screenshot of the last ~30 log lines, and the source/backup folder IDs (or confirm you can share them).

Contact

Questions, bugs, or ideas? Contact: dvanderpijll@align.com