Installs a single core PIP package from a specified branch on GitHub. By default (`force = FALSE`), the branch HEAD SHA is resolved and pinned, giving session-level deterministic installs. If the package is already at the target SHA, installation is skipped.
Arguments
- package
Character scalar. Core PIP package name. Defaults to `"pipapi"`.
- branch
Character scalar. Branch to install. When `NULL` (default), the package's configured default branch is used.
- force
Logical. If `TRUE`, bypasses SHA pinning and the idempotency check, installing the live branch HEAD (`@<branch>`) directly. Intended for developers. Default `FALSE`.
- sha
Character scalar. Optional commit SHA to install at. When supplied, overrides the resolved branch HEAD SHA. When `NULL` (default, and `force = FALSE`), the branch HEAD SHA is resolved automatically.
Value
`NULL` invisibly when installation is skipped (already at target SHA), or the result of [remotes::install_github()] when an install is actually performed.
SHA pinning
When `force = FALSE` (the default): 1. Resolves the branch HEAD SHA from GitHub. 2. Checks if the locally installed package already matches that SHA. 3. If they match, skips installation (idempotent). Otherwise, installs at the resolved (or explicitly provided) SHA.
This ensures deterministic installs: running the same `install_branch()` call twice will not re-install.
Errors
- Aborts if `package` is not a core PIP package. - Aborts if `branch` is not in the package's available branches. - Aborts if the SHA cannot be resolved (network error or invalid ref).
Examples
if (FALSE) { # \dontrun{
# Install default branch of pipapi
install_branch()
# Install a specific branch
install_branch("pipfun", "ongoing")
# Force install (bypass SHA pinning)
install_branch("pipfun", "ongoing", force = TRUE)
# Install at a specific SHA
install_branch("pipfun", "ongoing", sha = "a1b2c3d")
} # }