upgit

Languages: English / 简体中文

Development: 开发手册（中文）

Upgit is a native & lightweight tool that helps you upload any file to your Github repository and then get a raw URL for it.

This is also useful with Typora as an image uploader, and with the VSCode extension.

Feature

• Integrate with VSCode via extension
• Support for Linux, Windows and macOS
• Upload any file to given remote github repo folder
• Upload from clipboard
• Custom auto renaming rules
• CDN via replacing rules
• Config via Environment Variable
• Output URL to stdout/clipboard, supports markdown image format

Supported Upload Extensions

• Github

• GitLab

• S3 Compatible Storages

  • AWS S3
  • MinIO
  • Cloudflare R2
  • Ceph
  • Backblaze
  • Flexify.IO
  • IBM Cloud Object Storage
  • DigitalOcean Spaces
  • Wasabi

• Gitee (they block public image-bed repos; prefer SM.MS / S3 / OSS)

• Tencent QcloudCOS

• Qiniu Kodo

• Upyun

• AliyunOSS

• Hello

• Niupic

• SM.MS

• Imgur

• ImgUrl.org

• CatBox

• LSkyPro

• Chevereto

• ImgBB

• Cloudinary

• EasyImage

• DALEXNI

• img.tg

• Juejin

• Moetu

• NetEase

• Sogou

• upload.cc

• Lsky Pro v2

More: upgit uploaders

Get started

Download

Download the latest zip from Releases.

If you have no idea which to download:

• For most Windows users, choose upgit_win_amd64.zip
• For Windows ARM, choose upgit_win_arm64.zip
• For Windows 32-bit, choose upgit_win_386.zip
• For Linux x64, choose upgit_linux_amd64.zip
• For Linux arm64, choose upgit_linux_arm64.zip
• For Linux 32-bit, choose upgit_linux_386.zip
• For Linux ARM, choose upgit_linux_arm.zip
• For most macOS users, choose upgit_macos_arm64.zip
• For macOS Intel, choose upgit_macos_amd64.zip
• Execute chmod +x upgit if permission is needed

Unzip it, rename the binary to upgit (For Windows users, upgit.exe), save it to somewhere you like. To access it from anywhere, add its directory to the PATH environment variable.

Run upgit update to replace this binary with the latest stable GitHub release. upgit update --beta / --alpha opt into those channels. config.toml and customized recipes are left in place.

Config

Run upgit init. It writes a GitHub config.toml and prints the path. You can also create config.toml in the same directory of upgit.

Fill it in following this sample config file.

The repository must be public. Private repos make raw URLs 404.

Personal Access Token (PAT): a classic token with the repo scope, or a fine-grained token with Contents: Read and write on that repository. Create a token at GitHub Settings → Developer settings → Personal access tokens.

Use it

To upload file logo.png with rename rules, execute:

./upgit logo.png
# for windows: .\\upgit.exe logo.png

Then you'll see a link to logo.png.

To upload file logo.png to remote folder /my_images/demo, execute:

./upgit logo.png -t /my_images/demo
# for Windows: .\\upgit.exe logo.png -t /my_images/demo

FILE can be a local path or an http(s) URL (downloaded, then uploaded).

---

For more help, type -h argument

…

Use it for Typora

Assuming your upgit program is saved at "C:\repo\\upgit\\upgit.exe".

Select File > Preferences...

Move to Image. Choose Custom Command as your Image Uploader.

Input upgit program location into Command textbox.

You can click Test Uploader button to make sure it works.

Now enjoy it!

Upload Clipboard Image

Upload the clipboard image as png:

./upgit --clipboard

Shortcuts for screenshot:

• On macOS, use Ctrl+Shift+Cmd+4
• On Linux/Ubuntu, use Ctrl+Shift+PrintScreen
• On Windows, use Shift+Win+s

On Linux, clipboard access needs xclip (X11) or wl-clipboard (Wayland).

Compatible with Snipaste (Windows): Snipaste bitmap screenshots can be uploaded the same way.

Upload Clipboard Files

Note: This feature is only supported on Windows.

Upload files copied in Explorer (CF_HDROP):

./upgit --clipboard-files

Save URL to Clipboard

Use --output clipboard (alias --output-type):

upgit logo.png --output clipboard
# or .\\upgit.exe --clipboard -o clipboard

Copy as Markdown format

Add argument -f markdown (alias --output-format):

upgit logo.png --output clipboard -f markdown
# or .\\upgit.exe --clipboard -o clipboard -f markdown

Then you'll get a markdown image link in your clipboard like:

Best practice with AHK

For Windows user:

1. Install AHK

2. Create this script upload_clipboard.ahk and run:

   ; Press Ctrl + F9 to upload clipboard image
   ^F9::
   RunWait, "upgit.exe" --clipboard --output clipboard --format markdown
   return
   

3. Then press WinShiftS to take screenshot. CtrlF9 to upload it and get its link to your clipboard!

Config Instructions

Key	Desc
username	Your Github username, like pluveto
repo	Your Github repository name, like upgit
branch	The branch for saving files, like master or main
pat	Personal Access Token. Visit GitHub Docs for more info
rename	Renaming rule. Path separator / will create directories if not exists. Supporting:
-- {year}	-- Year like 2006
-- {month}	-- Month like 01
-- {day}	-- Day like 02
-- {hour}	-- Hours of current time
-- {minute}	-- Minutes of current time
-- {second}	-- Seconds of current time
-- {unix_ts}	-- Unix timestamp in second. Like 1643373370.
-- {unix_tsms}	-- Unix timestamp in millisecond. Like 1644212979622.
--- {ext}	-- Extension like .png, and empty when the original file has no extension
-- {fname}	-- Original file base name like demo (without extension)
-- {fname_hash}	-- xxHash32 (seed 0) hex of {fname} (name without extension)
-- {fname_hash4}	-- xxHash32 hex of {fname}, first 4 digits
-- {fname_hash8}	-- xxHash32 hex of {fname} (full 8-digit digest)
-- {content_hash}	-- xxHash32 (seed 0) hex of the file contents
-- {content_hash4}	-- xxHash32 hex of the file contents, first 4 digits
-- {content_hash8}	-- xxHash32 hex of the file contents (full 8-digit digest)
-- {hmac}	-- HMAC-SHA256 hash of hmac_format, truncated to hmac_len
hmac_key	Secret key for calculation {hmac}
hmac_format	Format string for {hmac} calculation. Supporting all above placeholders.
hmac_len	Length of {hmac} hash. 0 means no truncation.

Here is a simplist sample config file:

rename = "{year}/{month}/upgit_{year}{month}{day}_{unix_ts}{ext}"
[uploaders.github]
pat = "ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
repo = "repo-name"
username = "username"
branch = "main"

The config file is searched in this order:

1. --config / --config-file
2. ./config.toml
3. $XDG_CONFIG_HOME/upgit/config.toml or %APPDATA%\\upgit\config.toml
4. ~/.upgit.config.toml
5. ~/.config/upgitrc
6. config.toml and upgit.toml next to the binary

--application-path changes the binary-dir lookup. After each upload, history.log and upgit.log are written in that directory unless --no-log. Uploads run one at a time unless --jobs is set.

Config via Environment Variables

• UPGIT_TOKEN
• UPGIT_RENAME
• UPGIT_USERNAME
• UPGIT_REPO
• UPGIT_BRANCH

Any config key can also be set with UPGIT_ and __ for nesting (Kong-style):

export UPGIT_DEFAULT=smms
export UPGIT_UPLOADERS__GITHUB__PAT=PASTE_YOUR_TOKEN
export UPGIT_UPLOADERS__GITHUB__USERNAME=your-user
export UPGIT_NAMING='{year}/{month}/{fname}_{unix}{ext}'

Custom output format

In following way:

[output_formats]
"bbcode" = "[img]{url}[/img]"
"html" = ''
"markdown-simple" = ""

Placeholder:

• {url}: URL to image
• {fname}: Original file basename
• {url_fname}: File basename from url

Example usage:

# Upload clipboard and save link to clipboard as bbcode format
upgit --clipboard -o clipboard -f bbcode

Appendix: upgrading from 0.2

If you used the previous Go 0.2 upgit, flags such as :clipboard and --output-type, config paths, and Qiniu credentials changed. There is no extensions/ directory. See Upgrading from 0.2.

Optional: cargo install --git https://github.com/pluveto/upgit