Skip to content

Latest commit

 

History

History
104 lines (82 loc) · 4.37 KB

DOCS.md

File metadata and controls

104 lines (82 loc) · 4.37 KB

zeget Documentation

zeget works in several phases:

  • Load: load cache and configuration.
  • Query: query GitHub for the active rate limits.
  • Find: determine a list of assets that may be installed.
  • Detect: determine which asset in the list should be downloaded for the target system.
  • Verify: verify the checksum of the asset if possible.
  • Extract: determine which file within the asset to extract.

Load

The Load phase loads the cache and configuration files. The cache file is a JSON file that contains the last known rate limits and information on downloaded projects such as the last release date, the last asset downloaded, etc. It's also used to save previously selected assets for a project to avoid re-prompting the user for the same information.

Query

The Query phase queries api.github.com for the current rate limits. This is done to ensure that the user does not exceed the rate limits of the GitHub API.

Find

If the input is a repo identifier, the Find phase queries api.github.com with the repo and reads the list of assets from the response JSON. If a direct URL is provided, the Find phase just returns the direct URL without doing any work.

Detect

The Detect phase attempts to determine what OS and architecture each asset is built for. This is done by matching a regular expression for each OS/architecture that zeget knows about. The match rules are shown below, and are case insensitive.

OS Match Rule
darwin darwin|mac.?os|osx
windows win|windows
linux linux
netbsd netbsd
openbsd openbsd
freebsd freebsd
android android
illumos illumos
solaris solaris
plan9 plan9
Architecture Match Rule
amd64 x64|amd64|x86(-|_)?64
386 x32|amd32|x86(-|_)?32|i?386
arm arm
arm64 arm64|armv8|aarch64
riscv64 riscv64

If you would like a new OS/Architecture to be added, or find a case where the auto-detection is not adequate (within reason), please open an issue.

Using the direct OS/Architecture (left column of the above tables) name in your prebuilt zip file names will always allow zeget to auto-detect correctly, although zeget will often auto-detect correctly for other names as well.

Verify

During verification, zeget will attempt to verify the checksum of the downloaded asset. If the user has provided a checksum, or asked zeget to simply print the checksum, it will do so. Otherwise it may do auto-detection. If it is downloading an asset called xxx, and there is another asset called xxx.sha256 or xxx.sha256sum, zeget will automatically verify the SHA-256 checksum of the downloaded asset against the one contained in the .sha256/.sha256sum file.

Similarly, if there is an asset called checksums.txt, zeget will attempt to verify the checksum of the downloaded asset against the one contained in the checksums.txt file, and assumes it was generated by sha256sum or a similar tool.

Extract

During extraction, zeget will detect the type of archive and compression, and use this information to extract the requested file. If there is no requested file, zeget will extract a file with executable permissions, with priority given to files that have the same name as the repo. If multiple files with executable permissions exist and none of them match the repo name, zeget will ask the user to choose. Files ending in .exe or .appimage are also assumed to be executable, regardless of permissions within the archive.

zeget supports the following filetypes for assets:

  • .tar.gz/.tgz: tar archive with gzip compression.
  • .tar.bz2: tar archive with bzip2 compression.
  • .tar.xz: tar archive with xz compression.
  • .tar: tar archive with no compression.
  • .zip: zip archive.
  • .gz: single file with gzip compression.
  • .bz2: single file with bzip2 compression.
  • .xz: single file with xz compression.
  • otherwise: single file.

If a single file is "extracted" (no tar or zip archive), it will be marked executable automatically.