项目的 README,来自 github.com/shishir0x/GoogleUnlimited。合并为一个 markdown 文件:README.md。
Automated, cross-platform media synchronization utility for Google Photos.
Runs as a lightweight native background watcher on Windows, macOS, and Linux to automatically sync photos and videos using Google Pixel device emulation powered byxob0t/gotohp— without virtual machines, Android emulators, Windows Subsystem for Android (WSA), or WSL.
GoogleUnlimited monitors local folders on your computer and automatically synchronizes eligible photos and videos to your Google Photos library. It pairs native operating system event watchers (PowerShell on Windows, fswatch on macOS, and inotify-tools on Linux) with an embedded SQLite database (gphotos.db) and the standalone gotohp CLI binary.
The upload engine communicates directly with Google's mobile upload endpoints using Google Pixel device emulation. Because the requests present as a Pixel device, media backed up through this mechanism is processed according to Google Photos Pixel backup rules.
FileSystemWatcher with an expanded 64 KB event buffer and a 1.5-second debounce window to prevent redundant uploads on burst writes.fswatch for continuous low-latency filesystem event streaming.inotifywait (inotify-tools) listening to close_write, moved_to, and create kernel events.gphotos.db) using WAL mode.filename|filesize key paired with a SHA-256 content_hash. This prevents duplicate re-uploads on dual-boot machines or shared external drives where paths differ between operating systems.retry_queue table and automatically retried every 30 seconds for up to 3 attempts before logging a permanent failure.GoogleUnlimited.bat silent) and Windows Startup shortcut automation (GoogleUnlimited.lnk). Zero reliance on legacy script hosts.launchd LaunchAgent service management.systemd user service with lingering session support (loginctl enable-linger).Local\GoogleUnlimited_Watcher_<path>) prevents multiple concurrent watcher instances from running against the same installation directory..watcher.pid) and process inspection prevent conflicting background processes.gotohp.config) and database files are restricted to owner-only permissions (chmod 600 on Unix).photoslibrary.googleapis.com); zero telemetry and no intermediate servers.| Platform | OS Version / Arch | Runtime & Shell | Required Dependencies | Dependency Installation |
|---|---|---|---|---|
| Windows | Windows 10 / 11 (64-bit) | PowerShell 5.1 or PowerShell 7+ (pwsh) |
PSSQLite module |
Bundled in Modules/PSSQLite/; auto-installs via PowerShell Gallery if missing |
| macOS | macOS 11 (Big Sur)+ Apple Silicon (M1–M4) & Intel x64 |
Bash | fswatch, sqlite3, curl |
Auto-installed via Homebrew during ./google-unlimited.sh setup |
| Linux | Modern Linux distributions x86_64 or aarch64/arm64 |
Bash | inotify-tools, sqlite3, curl |
Auto-installed via apt, dnf, pacman, or zypper during ./google-unlimited.sh setup |
gotohp-cli-x64.exe: 64-bit Windows command-line upload engine (gotohp v0.11.0).gotohp-x64.exe: Windows desktop GUI helper for Google OAuth sign-in.gotohp-cli_amd64: Native Linux x86_64 binary../google-unlimited.sh setup.git clone https://github.com/shishir0x/GoogleUnlimited.git
cd GoogleUnlimited
gotohp-x64.exe.https://accounts.google.com) → copy the oauth_token value.gotohp and click Connect account, then close the window.GoogleUnlimited.bat and select [1] Start Live Watcher, or run:GoogleUnlimited.bat watch
git clone https://github.com/shishir0x/GoogleUnlimited.git
cd GoogleUnlimited
chmod +x google-unlimited.sh
./google-unlimited.sh setup
(Installs fswatch, sqlite3, downloads the universal binary, and verifies SHA-256 integrity).oauth_token cookie value../google-unlimited.sh creds add
Paste your token when prompted (input is hidden for security)../google-unlimited.sh watch
git clone https://github.com/shishir0x/GoogleUnlimited.git
cd GoogleUnlimited
chmod +x google-unlimited.sh
./google-unlimited.sh setup
(Installs inotify-tools, sqlite3, and curl using your system package manager).oauth_token value../google-unlimited.sh creds add
Paste the token into the hidden prompt. Alternatively, pipe the token:echo "<oauth_token>" | ./google-unlimited.sh creds add -
./google-unlimited.sh watch
GoogleUnlimited uses Google's Embedded Setup workflow to authenticate as an Android Google Photos client. This enables the mobile upload endpoint required for Google Pixel emulation.
When you log in through https://accounts.google.com/embedded/setup/v2/android and click I agree, Google expects a physical Android device to acknowledge the connection. In a web browser, the page will buffer or spin indefinitely. This is completely normal and expected. The authentication cookie has already been issued.
oauth_tokenhttps://accounts.google.com.https://accounts.google.com.accounts.google.com.oauth_token and copy its entire string value.gotohp.config in the root repository directory.gotohp.config is excluded by .gitignore and must never be committed to version control.chmod 600 so only your user account can read or write the file../google-unlimited.sh creds add, terminal echo is disabled to prevent the token from appearing in terminal history, process listings (ps), or shoulder surfing.# List all configured accounts (the active account is marked with an asterisk *)
./google-unlimited.sh creds list
# Switch the active upload account
./google-unlimited.sh creds set [email protected]
# Remove a configured account
./google-unlimited.sh creds remove [email protected]
On Windows, you can also manage accounts via GoogleUnlimited.bat account or by selecting option [9] from the menu.
GoogleUnlimited.bat / PowerShell)Running GoogleUnlimited.bat without arguments opens the interactive management menu:
==========================================================
* Google Unlimited Photos Auto-Sync (Windows)
==========================================================
[1] Start Live Watcher (Interactive progress)
[2] Start Background Watcher (Silent, zero window)
[3] Check Backup Status
[4] View Activity Logs
[5] Enable Auto-Start on Windows Boot
[6] Disable Auto-Start on Windows Boot
[7] Stop Background Watcher
[8] Manage Watched Folders (Add/List custom folders)
[9] Manage Google Accounts (List/Switch account)
[10] Force Re-scan & Sync All Media
[11] Check / Update Application (Keep configs safe)
[0] Exit
==========================================================
You can also run commands directly from the command prompt or terminal:
| Batch Command | Underlying PowerShell Flag | Menu Option | Description |
|---|---|---|---|
GoogleUnlimited.bat watch [dirs...] |
.\WatchAndUpload.ps1 [dirs...] |
[1] |
Start the live foreground watcher with dynamic progress bars and ETAs. |
GoogleUnlimited.bat silent |
powershell.exe -WindowStyle Hidden -File .\WatchAndUpload.ps1 |
[2] |
Start the background watcher silently (zero console window). |
GoogleUnlimited.bat status |
.\WatchAndUpload.ps1 -StatusOnly |
[3] |
View total uploads, pending retries, service state, and last 10 uploads. |
GoogleUnlimited.bat logs |
.\WatchAndUpload.ps1 -ShowLogs |
[4] |
Display the last 30 sync activity entries from the database. |
GoogleUnlimited.bat enable |
.\WatchAndUpload.ps1 -EnableStartup |
[5] |
Create a shortcut in the Windows Startup folder to run on boot. |
GoogleUnlimited.bat disable |
.\WatchAndUpload.ps1 -DisableStartup |
[6] |
Remove the shortcut from the Windows Startup folder. |
GoogleUnlimited.bat stop |
.\WatchAndUpload.ps1 -StopWatcher |
[7] |
Terminate any active background watcher processes. |
GoogleUnlimited.bat dirs |
.\WatchAndUpload.ps1 -ManageDirs |
[8] |
Open the interactive folder manager or Windows folder browser dialog. |
GoogleUnlimited.bat account |
gotohp-cli creds |
[9] |
List configured accounts, switch the active account, or open the GUI. |
GoogleUnlimited.bat resync |
.\WatchAndUpload.ps1 -ForceResync |
[10] |
Perform a full scan and force re-sync of all media across watched directories. |
GoogleUnlimited.bat update |
.\WatchAndUpload.ps1 -UpdateApp |
[11] |
Check and apply application updates safely while preserving configs & database. |
google-unlimited.sh)Running ./google-unlimited.sh without arguments in an interactive terminal opens the Unix manager menu:
==========================================================
* GoogleUnlimited - Unix Manager (Linux/Darwin)
==========================================================
[1] Start Live Watcher (Foreground)
[2] Check Backup Status
[3] View Activity Logs
[4] Run Setup & Dependency Installer
[5] Enable Auto-Start on Boot (launchd / systemd)
[6] Disable Auto-Start on Boot
[7] Stop Background Watcher
[8] Verify Binary Integrity
[9] Check / Update Application (Keep configs safe)
[0] Exit
==========================================================
You can execute any command directly from the shell:
| Shell Command | Menu Option | Description |
|---|---|---|
./google-unlimited.sh watch [dirs...] |
[1] |
Start the live sync watcher in the foreground. |
./google-unlimited.sh status |
[2] |
Display upload statistics, retry queue count, and recent sync records. |
./google-unlimited.sh logs |
[3] |
View the last 30 sync activity log records with color-coded severity. |
./google-unlimited.sh setup |
[4] |
Install platform dependencies, download missing binaries, and set file permissions. |
./google-unlimited.sh enable |
[5] |
Enable auto-start on login (launchd on macOS, systemd user service on Linux). |
./google-unlimited.sh disable |
[6] |
Disable and remove the auto-start background service. |
./google-unlimited.sh stop |
[7] |
Stop all active background watcher instances and filesystem listeners. |
./google-unlimited.sh verify |
[8] |
Verify the cryptographic SHA-256 integrity of the gotohp-cli binary. |
./google-unlimited.sh update |
[9] |
Check and apply application updates safely while preserving configs & database. |
./google-unlimited.sh creds [subcommand] |
— | Manage accounts: creds add, creds list, creds set <email>, creds remove <email>. |
./google-unlimited.sh menu |
— | Explicitly open the interactive terminal menu. |
./google-unlimited.sh help |
— | Display command-line usage information. |
watch_dirs.txt does not exist):Pictures (user Pictures folder)Downloads (resolved via registry or %USERPROFILE%\Downloads)%USERPROFILE%\OneDrive\Pictures, %USERPROFILE%\OneDrive\Pictures\Camera Roll%USERPROFILE%\Pictures\iCloud Photos\Photos%USERPROFILE%\Google Drive\Google Photos, %USERPROFILE%\Google Photos
(Note: Other Windows folders like Desktop, Videos, Documents, and Music can be added easily using GoogleUnlimited.bat dirs).$HOME/Pictures$HOME/Downloads$HOME/Google Photos$HOME/OneDrive/Pictures$HOME/Pictures/iCloud Photos/Photos
(If none exist, $HOME/Pictures is created and watched).watch_dirs.txt)When a watch_dirs.txt file exists in the repository root, the watcher switches to custom mode and monitors only the directories specified in that file (plus any directories passed via command-line arguments).
watch_dirs.txt in the repository root (or use GoogleUnlimited.bat dirs on Windows).# are ignored as comments. Environment variables are automatically expanded:# Standard media directories
%USERPROFILE%\Pictures
%USERPROFILE%\Downloads
# External drives or SD cards
D:\Camera_Imports
E:\Sony_A7_Media
# macOS / Linux paths
$HOME/Google Photos
${HOME}/Media
~/Pictures
/Volumes/ExternalSSD/Photos
On macOS and Linux, $VAR, ${VAR}, and a leading ~ are expanded. Unknown
variables are left unchanged, and shell expressions are never executed.GoogleUnlimited.bat watch "D:\Photos" "E:\Videos"
./google-unlimited.sh watch /Volumes/ExternalSSD/Photos /Volumes/ExternalSSD/Videos
Files are checked against a verified whitelist of extensions (case-insensitive) and must be at least 10 KB in size:
.jpg, .jpeg, .png, .heic, .heif, .webp, .gif, .bmp, .tiff, .tif, .svg, .ico, .jfif, .avif.dng, .raw, .cr2, .cr3 (Canon), .nef (Nikon), .arw (Sony), .orf (Olympus), .rw2 (Panasonic), .pef (Pentax), .srw (Samsung), .raf (Fujifilm).mp4, .mov (Apple QuickTime/iPhone), .mkv, .avi, .m4v, .3gp, .3g2, .wmv, .webm, .mpg, .mpeg, .mts, .m2ts, .ts, .flv, .vobFiles with temporary or partial extensions (such as .tmp, .crdownload, .part, .db, .config) and files inside Modules/ are strictly excluded.
To prevent corrupt or partial uploads:
lsof or fuser to verify no other process holds an open write handle.GoogleUnlimited.bat silent or option [2]. This launches WatchAndUpload.ps1 with -WindowStyle Hidden natively via PowerShell, creating no visible console window.GoogleUnlimited.bat enable or option [5]. This creates a Windows shortcut named GoogleUnlimited.lnk in your user Startup directory:%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\GoogleUnlimited.lnk
The shortcut points directly to PowerShell executing WatchAndUpload.ps1 with -WindowStyle Hidden in your repository folder.GoogleUnlimited.bat disable or option [6] to delete the shortcut.GoogleUnlimited.bat stop or option [7]. This cleanly terminates any active PowerShell processes running WatchAndUpload.ps1../google-unlimited.sh enable or option [5].~/Library/LaunchAgents/com.googleunlimited.watcher.plist
launchctl load -w. The watcher will start automatically when you log in to macOS and restart if it unexpectedly exits../google-unlimited.sh disable or option [6]. This unloads the service with launchctl unload -w and removes the .plist file../google-unlimited.sh stop or option [7]. Stops the LaunchAgent, signals the running PID recorded in .watcher.pid, and stops active fswatch processes../google-unlimited.sh enable or option [5].systemd user service unit at:~/.config/systemd/user/google-unlimited.service
systemctl --user daemon-reload, enables, and starts the service.loginctl enable-linger (if available), allowing the background sync service to run even before graphical login.systemctl --user status google-unlimited.service
./google-unlimited.sh disable or option [6]. Stops and disables the service and removes the unit file../google-unlimited.sh stop or option [7]. Stops the systemd service, terminates the PID in .watcher.pid, and stops any background inotifywait instances.WatchAndUpload.ps1 uses a named Windows Mutex (Local\GoogleUnlimited_Watcher_<cleanBase>). If an existing watcher instance is already running for the current directory, subsequent invocations exit immediately with code 0. GoogleUnlimited.bat silent executes a -CheckRunning validation to ensure duplicate processes are never spawned..watcher.pid. The stop command inspects .watcher.pid and checks process listings (pgrep) to cleanly terminate active watchers and listeners without affecting other system tasks.gphotos.db)All synchronization history is tracked locally in SQLite using WAL (Write-Ahead Logging) mode:
-- Tracks uploaded media files
CREATE TABLE uploads (
path TEXT PRIMARY KEY,
media_key TEXT,
uploaded_at TEXT NOT NULL DEFAULT (datetime('now','localtime')),
file_name TEXT,
file_size INTEGER,
content_hash TEXT
);
-- Tracks files pending retry
CREATE TABLE retry_queue (
path TEXT PRIMARY KEY,
attempts INTEGER NOT NULL DEFAULT 0,
last_attempt TEXT
);
-- Operational activity logs (auto-purged after 30 days)
CREATE TABLE logs (
id INTEGER PRIMARY KEY AUTOINCREMENT,
timestamp TEXT NOT NULL DEFAULT (datetime('now','localtime')),
level TEXT NOT NULL,
message TEXT NOT NULL
);
accounts.google.com and photoslibrary.googleapis.com). There are no third-party telemetry, metrics, or relay servers.gotohp.config..gitignore protects sensitive data:*.db
*.db-wal
*.db-shm
gphotos.db
watch_dirs.txt
gotohp.config
*.config
*.token
*.log
Personal database records, credentials, and local watch folder lists are never committed to git.gotohp.config, or no account is marked as active.GoogleUnlimited.bat account → Option [2] to open gotohp-x64.exe, sign in, and connect.oauth_token cookie via browser DevTools, then run:./google-unlimited.sh creds add
*) is displayed:./google-unlimited.sh creds list
GoogleUnlimited.bat status to check if the background watcher is active.GoogleUnlimited.bat stop (or select option [7]).com.apple.quarantine) to downloaded binaries../google-unlimited.sh setup to automatically strip quarantine flags and set execution permissions (chmod 700).Downloads.GoogleUnlimited.bat automatically passes -ExecutionPolicy Bypass. If running WatchAndUpload.ps1 directly, run:powershell.exe -ExecutionPolicy Bypass -File .\WatchAndUpload.ps1
GoogleUnlimited.bat logs (or menu option [4])../google-unlimited.sh logs (or menu option [3]).gphotos.db to troubleshoot minor issues. Deleting gphotos.db resets your local upload history and will cause GoogleUnlimited to re-evaluate and re-upload all existing media.Range: headers (HTTP 206 Partial Content) for random byte-range seeking on original media files. The built-in Google Photos web/mobile player can seek and resume because Google generates lower-resolution transcoded DASH/HLS streams on their backend (which strips secondary audio tracks, Dolby/DTS audio, and embedded subtitle tracks).--vfs-cache-mode full:rclone serve webdav gphotos: --vfs-cache-mode full --vfs-read-chunk-size 32M --vfs-read-chunk-size-limit 2G
Rclone intercepts the video player's byte-range requests and downloads sparse chunks on demand, synthesizing standard HTTP 206 responses locally so seeking and resuming work seamlessly.advancedsettings.xml with disk/RAM buffering (<buffermode>1</buffermode>), or in Nova Video Player enable Cache to disk under video player settings to allow local seek within buffered segments.GoogleUnlimited-main.zip from GitHub in Chrome or Edge, the browser displays GoogleUnlimited-main.zip Failed - Virus detected, or Windows Defender / third-party antivirus flags a generic heuristic alert (e.g. Trojan:Win32/Wacatac or Trojan.Gen).gotohp-x64.exe / gotohp-cli-x64.exe) is an open-source Go client (xob0t/gotohp) that communicates directly with Google Photos internal mobile upload endpoints, emulating Google Pixel device headers to qualify for unlimited backup storage. Because it is unsigned and spoofs mobile hardware device properties over HTTPS, generic heuristic engines flag it as a false positive.StartPhotosWatcher.vbs) and in-memory P/Invoke kernel32 calls, which triggered script-host behavioral heuristics. These have been completely eliminated from the codebase in favor of clean, native PowerShell automation.git clone https://github.com/shishir0x/GoogleUnlimited.git
cd GoogleUnlimited
Ctrl + J to open the Downloads page.GoogleUnlimited-main.zip, click Details (or ... menu), and select Keep anyway / Keep dangerous file.Get-FileHash gotohp-cli-x64.exe -Algorithm SHA256
gotohp-cli-x64.exe: C272A285A03AEEA02A909F0B74D36F84C4A29C235C8DEE47F7DE75C83F15D2B1gotohp-x64.exe: 5C3F757B9E6B2FFD83934B59274136CF4E67C000265E2EAAA4F34DCA6A821088gotohp-cli_amd64: 945021D5DBC36A96F53121EB4F907ACE39D9457CEA1B43107ED1986441B29030gotohp. Google may modify its APIs, authentication mechanisms, device eligibility criteria, or storage policies at any time. No guarantee of permanent, uninterrupted service or indefinite zero-quota storage can be made.watch_dirs.txt are monitored while mounted. If an external drive is disconnected, monitoring will resume once reconnected and rescanned.xob0t/gotohp by xob0t (licensed under the GNU General Public License v3.0).PSSQLite by RamblingCookieMonster (licensed under the Apache License 2.0).