On this page:
6.1 Linking a Git Checkout as a Directory
6.2 Linking a Git Checkout as a Clone
6.3 Interactions Between git and raco pkg
8.6.0.4

6 Developing Packages with Git

When a Git repository is specified as a package source, then a copy of the repository content is installed as the package implementation. That installation mode is designed for package consumers, who normally use a package without modifying it. The installed copy of the package is unsuitable for development by the package author, however, since the installation is not a full clone of the Git repository. The Racket package manager provides different installation modes to support package authors who work with Git repository clones.

6.1 Linking a Git Checkout as a Directory

Since a Git repository checkout is a directory, it can be linked as a package as described in Linking and Developing New Packages. In that case, any modifications made locally take effect immediately for the package installation, including any updates from a git pull. The developer must explicitly pull any remote updates to the repository, however, including when the updates are needed to satisfy the requirements of dependent packages.

In the following section, we describe an alternative that makes raco pkg update aware of the checkout directory’s status as a repository clone. Furthermore, a directory-linked package can be promoted to a clone-linked package with raco pkg update.

6.2 Linking a Git Checkout as a Clone

When a package is installed with

  raco pkg install --clone dir git-pkg-source

then instead of installing the package as a mere copy of the repository source, the package is installed by creating a Git clone of git-pkg-source as dir. The clone’s checkout is linked in the same way as a directory, but unlike a plain directory link, the Racket package manager keeps track of the repository connection. The git-pkg-source must be a Git or GitHub package source, or it must be a package name that the catalog maps to a Git or GitHub package source; if the source URL includes a fragment, it must name a branch or tag (as opposed to a raw commit). If git-pkg-source refers to a repository over HTTPS but has no .git suffix, use git+https:// to refer to the repository.

When the repository at git-pkg-source is changed so that the source has a new checksum, then raco pkg update for the package pulls commits from the repository to the local clone. In other words, raco pkg update works as an alternative to git pull --ff-only to pull updates for the package. Furthermore, raco pkg update can pull updates to local package repositories when checking dependencies. For example, raco pkg update --all pulls updates for all linked package repositories.

A package source provided with --clone can include a branch and/or path into the repository. The branch specification affects the branch used for the initial checkout, while a non-empty path causes a subdirectory of the checkout to be linked for the package.

Suppose that a developer works with a large number of packages and develops only a few of them. The intended workflow is as follows:

6.3 Interactions Between git and raco pkg

The git and raco pkg tools interact in specific ways: