Tags, versions and GitHub Releases

from gitsession import session

session(r"""
git init -q numfmt
cd numfmt
printf '__version__ = "0.1.0"\n' > numfmt.py
git add numfmt.py
git commit -q -m "Group digits the Indian way"
# A lightweight tag: only a name for a commit
git tag v0.1.0
printf '__version__ = "0.2.0"\n' > numfmt.py
git commit -q -am "Format amounts with two decimal places"
# An annotated tag: an object of its own, with a tagger, a time and a message
git tag -a v0.2.0 -m "numfmt 0.2.0: amounts with two decimal places"
git tag
git cat-file -t v0.1.0
git cat-file -t v0.2.0
git cat-file -p v0.2.0
git show-ref --tags --dereference
git describe
! git describe HEAD~1
git describe --tags HEAD~1
""")

$ git init -q numfmt
$ cd numfmt
$ printf '__version__ = "0.1.0"\n' > numfmt.py
$ git add numfmt.py
$ git commit -q -m "Group digits the Indian way"
# A lightweight tag: only a name for a commit
$ git tag v0.1.0
$ printf '__version__ = "0.2.0"\n' > numfmt.py
$ git commit -q -am "Format amounts with two decimal places"
# An annotated tag: an object of its own, with a tagger, a time and a message
$ git tag -a v0.2.0 -m "numfmt 0.2.0: amounts with two decimal places"
$ git tag
v0.1.0
v0.2.0
$ git cat-file -t v0.1.0
commit
$ git cat-file -t v0.2.0
tag
$ git cat-file -p v0.2.0
object 1151ef0592f6c1bf1b62e62df1538a7c49fcfe1e
type commit
tag v0.2.0
tagger Asha Rao <asha@example.com> 1767240000 +0530

numfmt 0.2.0: amounts with two decimal places
$ git show-ref --tags --dereference
6929d5f3bb63534d2b5a834adf4dc0a63c507bda refs/tags/v0.1.0
8fe03c34aea1120d1161d9f1c5d557835fc431eb refs/tags/v0.2.0
1151ef0592f6c1bf1b62e62df1538a7c49fcfe1e refs/tags/v0.2.0^{}
$ git describe
v0.2.0
$ git describe HEAD~1
fatal: No annotated tags can describe '6929d5f3bb63534d2b5a834adf4dc0a63c507bda'.
However, there were unannotated tags: try --tags.
[exit status 128]
$ git describe --tags HEAD~1
v0.1.0

from gitsession import session

session(r"""
git init -q numfmt
cd numfmt
git commit -q --allow-empty -m "History of numfmt"
git tag v1.9.0
git tag v1.10.0
git tag v2.0.0-alpha
git tag v2.0.0-beta.2
git tag v2.0.0-beta.11
git tag v2.0.0-rc.1
git tag v2.0.0
# Alphabetical, the default
git tag
# As versions: 1.10 after 1.9, but every pre-release after 2.0.0
git tag --sort=version:refname
# Tell Git which suffixes mark a pre-release, in their order
git config versionsort.suffix -alpha
git config --add versionsort.suffix -beta
git config --add versionsort.suffix -rc
git tag --sort=version:refname
git tag --sort=-version:refname --list 'v2*'
""")

$ git init -q numfmt
$ cd numfmt
$ git commit -q --allow-empty -m "History of numfmt"
$ git tag v1.9.0
$ git tag v1.10.0
$ git tag v2.0.0-alpha
$ git tag v2.0.0-beta.2
$ git tag v2.0.0-beta.11
$ git tag v2.0.0-rc.1
$ git tag v2.0.0
# Alphabetical, the default
$ git tag
v1.10.0
v1.9.0
v2.0.0
v2.0.0-alpha
v2.0.0-beta.11
v2.0.0-beta.2
v2.0.0-rc.1
# As versions: 1.10 after 1.9, but every pre-release after 2.0.0
$ git tag --sort=version:refname
v1.9.0
v1.10.0
v2.0.0
v2.0.0-alpha
v2.0.0-beta.2
v2.0.0-beta.11
v2.0.0-rc.1
# Tell Git which suffixes mark a pre-release, in their order
$ git config versionsort.suffix -alpha
$ git config --add versionsort.suffix -beta
$ git config --add versionsort.suffix -rc
$ git tag --sort=version:refname
v1.9.0
v1.10.0
v2.0.0-alpha
v2.0.0-beta.2
v2.0.0-beta.11
v2.0.0-rc.1
v2.0.0
$ git tag --sort=-version:refname --list 'v2*'
v2.0.0
v2.0.0-rc.1
v2.0.0-beta.11
v2.0.0-beta.2
v2.0.0-alpha

from gitsession import session

session(r"""
# A shared repository (a folder here) and Asha's clone of it
git init -q --bare numfmt.git
git clone -q numfmt.git numfmt
cd numfmt
printf '__version__ = "1.0.0"\n' > numfmt.py
git add numfmt.py
git commit -q -m "Group digits the Indian way"
git tag -a v1.0.0 -m "numfmt 1.0.0"
git tag try-new-rounding
git push -q origin main
# Pushing a branch sends no tags
git ls-remote --tags origin
# --follow-tags also sends the annotated tags of the commits being pushed
git push --follow-tags origin main
git ls-remote --tags origin
# --tags would send every tag, the private lightweight one too
git push --tags --dry-run origin
git tag -d try-new-rounding
cd ..
# Ravi's new clone gets every tag on the server
git clone -q numfmt.git ravi
cd ravi
git tag
git describe
""")

# A shared repository (a folder here) and Asha's clone of it
$ git init -q --bare numfmt.git
$ git clone -q numfmt.git numfmt
warning: You appear to have cloned an empty repository.
$ cd numfmt
$ printf '__version__ = "1.0.0"\n' > numfmt.py
$ git add numfmt.py
$ git commit -q -m "Group digits the Indian way"
$ git tag -a v1.0.0 -m "numfmt 1.0.0"
$ git tag try-new-rounding
$ git push -q origin main
# Pushing a branch sends no tags
$ git ls-remote --tags origin
# --follow-tags also sends the annotated tags of the commits being pushed
$ git push --follow-tags origin main
To ~/numfmt.git
 * [new tag]         v1.0.0 -> v1.0.0
$ git ls-remote --tags origin
a0f0f759679b07e6f9503f040c23059cdeb546d1	refs/tags/v1.0.0
ff78e14bd065c87b16f24ce7f179277b78722434	refs/tags/v1.0.0^{}
# --tags would send every tag, the private lightweight one too
$ git push --tags --dry-run origin
To ~/numfmt.git
 * [new tag]         try-new-rounding -> try-new-rounding
$ git tag -d try-new-rounding
Deleted tag 'try-new-rounding' (was ff78e14)
$ cd ..
# Ravi's new clone gets every tag on the server
$ git clone -q numfmt.git ravi
$ cd ravi
$ git tag
v1.0.0
$ git describe
v1.0.0

from gitsession import session

session(r"""
git init -q --bare numfmt.git
git clone -q numfmt.git numfmt
cd numfmt
printf '__version__ = "1.0.0"\n' > numfmt.py
git add numfmt.py
git commit -q -m "Release 1.0.0"
git tag -a v1.0.0 -m "numfmt 1.0.0"
git push -q --follow-tags origin main
cd ..
git clone -q numfmt.git ravi
cd numfmt
# Asha finds a bug after the release and moves the tag to the fix
printf '__version__ = "1.0.0"\nFIXED = True\n' > numfmt.py
git commit -q -am "Fix rounding of negative amounts"
git tag -f -a v1.0.0 -m "numfmt 1.0.0"
! git push origin v1.0.0
git push --force origin main v1.0.0
cd ../ravi
# Ravi fetches: the new commit arrives, the moved tag does not
git fetch
! git fetch --tags
git rev-parse --short v1.0.0^{commit}
git -C ../numfmt rev-parse --short v1.0.0^{commit}
""")

$ git init -q --bare numfmt.git
$ git clone -q numfmt.git numfmt
warning: You appear to have cloned an empty repository.
$ cd numfmt
$ printf '__version__ = "1.0.0"\n' > numfmt.py
$ git add numfmt.py
$ git commit -q -m "Release 1.0.0"
$ git tag -a v1.0.0 -m "numfmt 1.0.0"
$ git push -q --follow-tags origin main
$ cd ..
$ git clone -q numfmt.git ravi
$ cd numfmt
# Asha finds a bug after the release and moves the tag to the fix
$ printf '__version__ = "1.0.0"\nFIXED = True\n' > numfmt.py
$ git commit -q -am "Fix rounding of negative amounts"
$ git tag -f -a v1.0.0 -m "numfmt 1.0.0"
Updated tag 'v1.0.0' (was e87d7ac)
$ git push origin v1.0.0
To ~/numfmt.git
 ! [rejected]        v1.0.0 -> v1.0.0 (already exists)
error: failed to push some refs to '~/numfmt.git'
hint: Updates were rejected because the tag already exists in the remote.
[exit status 1]
$ git push --force origin main v1.0.0
To ~/numfmt.git
   11d69fd..63472c7  main -> main
 + e87d7ac...ebcd6ed v1.0.0 -> v1.0.0 (forced update)
$ cd ../ravi
# Ravi fetches: the new commit arrives, the moved tag does not
$ git fetch
From ~/numfmt
   11d69fd..63472c7  main       -> origin/main
$ git fetch --tags
From ~/numfmt
 ! [rejected] v1.0.0     -> v1.0.0  (would clobber existing tag)
[exit status 1]
$ git rev-parse --short v1.0.0^{commit}
11d69fd
$ git -C ../numfmt rev-parse --short v1.0.0^{commit}
63472c7

from gitsession import session

session(r"""
git init -q numfmt
cd numfmt
printf '__version__ = "1.2.0"\n' > numfmt.py
git add numfmt.py
git commit -q -m "Release 1.2.0"
git tag -a v1.2.0 -m "numfmt 1.2.0"
git describe
# Three more commits after the release
printf 'def words(n): ...\n' > words.py
git add words.py
git commit -q -m "Start words()"
git commit -q --allow-empty -m "Handle zero in words()"
git commit -q --allow-empty -m "Handle negative numbers in words()"
git describe
git log --oneline v1.2.0..HEAD
# An uncommitted change makes the build different from every commit
printf '# work in progress\n' >> words.py
git describe --dirty
# Only the nearest tag, or the long form even on a tag
git describe --abbrev=0
git describe --long v1.2.0
# No tag yet: --always falls back to the commit ID
git init -q ../fresh
cd ../fresh
git commit -q --allow-empty -m "First commit"
! git describe
git describe --always --dirty
""")

$ git init -q numfmt
$ cd numfmt
$ printf '__version__ = "1.2.0"\n' > numfmt.py
$ git add numfmt.py
$ git commit -q -m "Release 1.2.0"
$ git tag -a v1.2.0 -m "numfmt 1.2.0"
$ git describe
v1.2.0
# Three more commits after the release
$ printf 'def words(n): ...\n' > words.py
$ git add words.py
$ git commit -q -m "Start words()"
$ git commit -q --allow-empty -m "Handle zero in words()"
$ git commit -q --allow-empty -m "Handle negative numbers in words()"
$ git describe
v1.2.0-3-g04a2159
$ git log --oneline v1.2.0..HEAD
04a2159 Handle negative numbers in words()
1d8674b Handle zero in words()
0ed8a4c Start words()
# An uncommitted change makes the build different from every commit
$ printf '# work in progress\n' >> words.py
$ git describe --dirty
v1.2.0-3-g04a2159-dirty
# Only the nearest tag, or the long form even on a tag
$ git describe --abbrev=0
v1.2.0
$ git describe --long v1.2.0
v1.2.0-0-gacaa4b7
# No tag yet: --always falls back to the commit ID
$ git init -q ../fresh
$ cd ../fresh
$ git commit -q --allow-empty -m "First commit"
$ git describe
fatal: No names found, cannot describe anything.
[exit status 128]
$ git describe --always --dirty
e03cb2e

"""Orders version numbers by the precedence rules of Semantic Versioning 2.0.0 (item 11 of the specification)."""

import re
from functools import cmp_to_key

IDENTIFIER = re.compile(r"[0-9A-Za-z-]+")


def parse(version):
    """Splits "1.0.0-rc.1+build.5" into ((1, 0, 0), ["rc", "1"], ["build", "5"]), or raises ValueError."""
    rest, plus, build = version.partition("+")
    core, dash, pre = rest.partition("-")
    numbers = core.split(".")
    if len(numbers) != 3 or not all(n.isascii() and n.isdigit() for n in numbers):
        raise ValueError("needs MAJOR.MINOR.PATCH, three numbers")
    if any(len(n) > 1 and n.startswith("0") for n in numbers):
        raise ValueError("a number may not start with 0")
    pre_ids = pre.split(".") if dash else []
    build_ids = build.split(".") if plus else []
    for part in pre_ids + build_ids:
        if not IDENTIFIER.fullmatch(part):
            raise ValueError(f"identifier {part!r} must be ASCII letters, digits or hyphens, and not empty")
    for part in pre_ids:
        if part.isdigit() and len(part) > 1 and part.startswith("0"):
            raise ValueError(f"numeric identifier {part!r} may not start with 0")
    return tuple(int(n) for n in numbers), pre_ids, build_ids


def compare(a, b):
    """-1, 0 or 1. Build metadata is ignored, so 1.0.0+5 and 1.0.0+9 compare equal."""
    (core_a, pre_a, _), (core_b, pre_b, _) = parse(a), parse(b)
    if core_a != core_b:
        return -1 if core_a < core_b else 1
    if not pre_a or not pre_b:
        # A pre-release comes before the normal version with the same numbers.
        return (len(pre_a) < len(pre_b)) - (len(pre_a) > len(pre_b))
    for x, y in zip(pre_a, pre_b):
        if x == y:
            continue
        if x.isdigit() and y.isdigit():
            return -1 if int(x) < int(y) else 1
        if x.isdigit() != y.isdigit():
            return -1 if x.isdigit() else 1  # numbers come before words
        return -1 if x < y else 1  # words compare in ASCII order
    return (len(pre_a) > len(pre_b)) - (len(pre_a) < len(pre_b))


tags = ["2.0.0", "1.10.0", "2.0.0-rc.1", "2.0.0-beta.11", "1.9.0", "2.0.0-alpha", "2.0.0-beta.2", "2.0.0-alpha.1"]
print("SemVer order:", " < ".join(sorted(tags, key=cmp_to_key(compare))))

spec = "1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0"
expected = spec.split(" < ")
print("The specification's own example sorts the same:", sorted(reversed(expected), key=cmp_to_key(compare)) == expected)
print("1.0.0+build.5 against 1.0.0+build.9:", compare("1.0.0+build.5", "1.0.0+build.9"))

for text in ["v1.2.3", "1.2", "1.02.0", "1.0.0-rc.01", "1.0.0-", "1.0.0-rc_1"]:
    try:
        parse(text)
        print(f"{text}: valid")
    except ValueError as problem:
        print(f"{text}: not SemVer ({problem})")

SemVer order: 1.9.0 < 1.10.0 < 2.0.0-alpha < 2.0.0-alpha.1 < 2.0.0-beta.2 < 2.0.0-beta.11 < 2.0.0-rc.1 < 2.0.0
The specification's own example sorts the same: True
1.0.0+build.5 against 1.0.0+build.9: 0
v1.2.3: not SemVer (needs MAJOR.MINOR.PATCH, three numbers)
1.2: not SemVer (needs MAJOR.MINOR.PATCH, three numbers)
1.02.0: not SemVer (a number may not start with 0)
1.0.0-rc.01: not SemVer (numeric identifier '01' may not start with 0)
1.0.0-: not SemVer (identifier '' must be ASCII letters, digits or hyphens, and not empty)
1.0.0-rc_1: not SemVer (identifier 'rc_1' must be ASCII letters, digits or hyphens, and not empty)

# .github/release.yml: how GitHub groups merged pull requests when it generates release notes.
# Pull requests are grouped by their labels; "*" catches every one that matched no category above it.
changelog:
  exclude:
    labels:
      - skip-release-notes
  categories:
    - title: Breaking changes
      labels:
        - breaking-change
    - title: New features
      labels:
        - enhancement
    - title: Bug fixes
      labels:
        - bug
    - title: Other changes
      labels:
        - "*"

"""Release-tagging practice. The first run makes release-practice/: a shared repository (origin.git) and a clone of
it (numfmt) with three unreleased commits after v1.3.0. Tag each of them with the version it should get, as an
annotated tag, push the tags, and run this file again: it checks the tags in the clone and on the shared repository.
"""

import os
import subprocess
import sys
from pathlib import Path

PRACTICE = Path("release-practice")
CLONE = PRACTICE / "numfmt"
COMMITS = [
    ("Release 1.3.0", "1.3.0"),
    ("Fix: negative amounts lost their minus sign", "1.3.1"),
    ("Add words(), which spells out an amount", "1.4.0"),
    ("Remove group_indian(); call group() instead", "2.0.0"),
]
# The practice history is the same on every computer: one author, fixed times, no signing or hooks of yours.
WHO = {"GIT_AUTHOR_NAME": "Asha Rao", "GIT_AUTHOR_EMAIL": "asha@example.com",
       "GIT_COMMITTER_NAME": "Asha Rao", "GIT_COMMITTER_EMAIL": "asha@example.com"}
SAFE = ["-c", "commit.gpgSign=false", "-c", "tag.gpgSign=false", "-c", "core.hooksPath=no-hooks"]


def git(*args, cwd=CLONE, when=None):
    env = {**os.environ, **WHO}
    if when:
        env["GIT_AUTHOR_DATE"] = env["GIT_COMMITTER_DATE"] = f"@{when} +0530"
    done = subprocess.run(["git", *SAFE, *args], cwd=cwd, env=env, capture_output=True, text=True)
    return done.stdout.strip() if done.returncode == 0 else None


def make_practice():
    PRACTICE.mkdir()
    git("init", "-q", "--bare", "-b", "main", "origin.git", cwd=PRACTICE)
    git("clone", "-q", "origin.git", "numfmt", cwd=PRACTICE)
    for n, (message, _) in enumerate(COMMITS):
        (CLONE / "CHANGES.txt").write_text("".join(f"{m}\n" for m, _ in COMMITS[: n + 1]))
        git("add", "CHANGES.txt")
        git("commit", "-q", "-m", message, when=1767240000 + 86400 * n)
    git("tag", "-a", "v1.3.0", "-m", "numfmt 1.3.0", git("rev-list", "--max-parents=0", "HEAD"), when=1767240000)
    git("push", "-q", "--follow-tags", "origin", "main")
    print(f"Made {CLONE}: three commits since v1.3.0 wait for their tags.")


if not PRACTICE.exists():
    make_practice()

ids = dict(line.split(" ", 1)[::-1] for line in git("log", "--format=%H %s").splitlines())
remote = dict(line.split("\t")[::-1] for line in (git("ls-remote", "--tags", "origin") or "").splitlines())
passed = 0
for message, version in COMMITS[1:]:
    tags = (git("tag", "--points-at", ids[message]) or "").split()
    tag = f"v{version}"
    if not tags:
        print(f"✗ {message}: not tagged yet")
    elif tag not in tags:
        print(f"✗ {message}: tagged {', '.join(tags)}, which is not the number this change calls for")
    elif git("cat-file", "-t", tag) != "tag":
        print(f"✗ {message}: {tag} is a lightweight tag; a release gets an annotated one (git tag -a)")
    elif remote.get(f"refs/tags/{tag}") != git("rev-parse", tag):
        print(f"✗ {message}: {tag} is right, but origin does not have it yet")
    else:
        print(f"✓ {message}: {tag}, annotated, on origin")
        passed += 1
print(f"{passed} of 3 checks pass")
sys.exit(0 if passed == 3 else 1)

Made release-practice/numfmt: three commits since v1.3.0 wait for their tags.
✗ Fix: negative amounts lost their minus sign: not tagged yet
✗ Add words(), which spells out an amount: not tagged yet
✗ Remove group_indian(); call group() instead: not tagged yet
0 of 3 checks pass

"""Plays a terminal session with real Git: each command is printed after "$ ", then everything it printed.

The session runs in a new folder called learner/, which is also its home folder, so your own Git settings change
nothing, and GIT_CONFIG_NOSYSTEM=1 makes Git skip the computer's system-wide settings file too. Its ~/.gitconfig
holds only a name, an email address and init.defaultBranch = main, the settings the lesson on installing Git sets
up. In the output, "~" stands for that folder. Commit and tag times are fixed, because an object's ID covers the
time it was made: with the same files, messages, names and times, every run makes the same IDs. A command can still
set its own time, as in a shell: GIT_COMMITTER_DATE="@1767326400 +0530" git commit ...

Each line of a script is one /bin/sh command (macOS and Linux), except "cd", which the session does itself. A line
that starts with "# " is printed as a comment. A command written as "! command" is meant to fail: its exit status
is printed and the session goes on. Any other command that fails stops the session with exit status 1.

session() can also be given:
  user     the name and email address of the person at the keyboard (Asha Rao, asha@example.com by default);
  setup    commands that build the starting point first, without being shown (they are in the example's code);
  mask     (pattern, replacement) pairs for text that is new on every run, such as how long a command took;
  prepare  a function that receives the new home folder before any command runs, to put files into it;
  path     more folders in which to look for commands, such as the folder of a downloaded tool.
"""

import os
import re
import shutil
import subprocess
import sys
from pathlib import Path

HOME = Path("learner").resolve()
# One fixed moment in Git's own date format: seconds since 1970, then the time zone (India, UTC+05:30).
FIXED_TIME = "@1767240000 +0530"


def _environment(path):
    # Git's own folder comes first, so every command runs that Git directly (on macOS, /usr/bin/git is a small
    # launcher that looks Git up again on every call).
    git_folder = subprocess.run(["git", "--exec-path"], capture_output=True, text=True, check=True).stdout.strip()
    folders = [git_folder, *(str(Path(p).resolve()) for p in path), os.environ.get("PATH", "/usr/bin:/bin")]
    env = {
        "PATH": os.pathsep.join(folders),
        "HOME": str(HOME),
        "XDG_CONFIG_HOME": str(HOME / ".config"),
        "GIT_CONFIG_NOSYSTEM": "1",
        "GIT_AUTHOR_DATE": FIXED_TIME,
        "GIT_COMMITTER_DATE": FIXED_TIME,
        "LANG": "C",
        "LC_ALL": "C",
        "TERM": "dumb",
    }
    if "TMPDIR" in os.environ:
        env["TMPDIR"] = os.environ["TMPDIR"]
    return env


def _with_tilde(text):
    """Writes the home folder as "~", however the operating system spells its path."""
    for spelling in sorted({str(HOME), os.path.realpath(HOME)}, key=len, reverse=True):
        text = text.replace(spelling, "~")
    return text


def _commands(script):
    for line in script.strip().splitlines():
        if line.strip():
            yield line.strip()


def session(script, user=("Asha Rao", "asha@example.com"), setup="", mask=(), prepare=None, path=()):
    """Runs the script's commands one by one, starting in a new home folder."""
    shutil.rmtree(HOME, ignore_errors=True)
    HOME.mkdir()
    (HOME / ".gitconfig").write_text(f"[user]\n\tname = {user[0]}\n\temail = {user[1]}\n[init]\n\tdefaultBranch = main\n")
    if prepare:
        prepare(HOME)
    env = _environment(path)
    folder = HOME
    for command in _commands(setup):
        if command.startswith("# "):
            continue
        if command.startswith("cd "):
            folder = (folder / command[3:].strip()).resolve()
            continue
        done = subprocess.run(command, shell=True, cwd=folder, env=env, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True)
        if done.returncode != 0:
            sys.exit(f"setup command failed: {command}\n{_with_tilde(done.stdout)}")
    folder = HOME
    for command in _commands(script):
        if command.startswith("# "):
            print(command)
            continue
        meant_to_fail = command.startswith("! ")
        if meant_to_fail:
            command = command[2:]
        print("$", command)
        if command.startswith("cd "):
            folder = (folder / command[3:].strip()).resolve()
            continue
        done = subprocess.run(command, shell=True, cwd=folder, env=env, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True)
        output = _with_tilde(done.stdout)
        for pattern, replacement in mask:
            output = re.sub(pattern, replacement, output)
        if output and not output.endswith("\n"):
            output += "\n"
        print(output, end="")
        if done.returncode != 0:
            print(f"[exit status {done.returncode}]")
            if not meant_to_fail:
                sys.exit(1)
        elif meant_to_fail:
            sys.exit(f"{command} was meant to fail, but it worked")