• Introduction
  • This package adds two Git commands
  • In short
• Installation
  • Install with make
  • ZI
• Extra info
  • Known limitations
  • Encoding the file paths

Introduction

This package adds two Git commands

• url – generates so called giturl which encodes repository fetch-URL and revision (can also hold paths to files); example giturl: gitu://ҝjȩMżEäḝЃȣϟṈӛŀї (points to main branch of this project),
• guclone – clones given giturl, checkouts revision stored in this giturl.

In short

1. The giturls use 1024 unicode letters via base-1024 encoding, and also Huffman codes, to compress resulting string.
   • SMALL SIZE
2. Thanks to using glyphs that are letters (not symbols) double clicking on giturl always selects whole string, regardless if it's done in e.g. Firefox, Chrome, iTerm2, xterm, etc.
   • CALM SELECTING
3. git url ... and git guclone ... understand giturls also without leading gitu://, and with leading //, so grabbing and using such url is easy.
   • EASY USE
4. You can encode path to file in the giturl, to e.g. point someone to a location in project.
   • PACKED WITH DATA

Compare length of the above example giturl to the data it stores:

ҝjȩMżEäḝЃȣϟṈӛŀї
https://github.com/z-shell/git-url

Installation

Install with make

Recursively clone and run make install. Default install location is /usr/local. It can be overriden by setting PREFIX, e.g. make install PREFIX=/opt.

git clone --recursive https://github.com/z-shell/git-url
cd git-url
make install

ZI

If you use ZI, then there's a nice way of installing:

zi ice as"program" pick"$ZPFX/bin/git-(url|guclone)" make"install PREFIX=$ZPFX"
zi light z-shell/git-url

To update, execute zi update z-shell/git-url. $ZPFX is ~/.zi/polaris by default.

Extra info

Note: cgiturl backend temporary disabled due to deprecation, however zgiturl backend tested and is fully functional.

The project uses two subprojects, one of them written in C++ (compiled with CMake), second one in Zshell. They are the computation backends, and any of the two will work (choose with export GITURL_TOOL=zgiturl or ...=cgiturl).

Known limitations

Only a subset of ASCII is encoded. This is sufficient for typical Github usage, where user and repository name are required to not use symbols, and where typical project branch names and file names are simple ASCII. Following characters can appear in input data – in the server, repository path, user name, revision, file path: [a-zA-Z0-9._~:/-].

Encoding the file paths

Use -p option to embed path to file in giturl:

❯ git-url
Encoding... INPUT is next paragraph:

Protocol: ssh
User:     git
Site:     github.com
Repo:     z-shell/git-url.git
Revision: main

gitu://VъöчŅϠѝŌĜEäḝЃȯŅǍǴḀЧ
❯ git clone gitu://VъöчŅϠѝŌĜEäḝЃȯŅǍǴḀЧ

Suggested is to use tilde ~ to separate multiple file paths. The project can be easily extended if this workaround will not suffice, to encode multiple file paths natively.