Branch Configuration and Options • metapip

Background

Many metapip functions accept a branch argument. This vignette explains the three-level priority system for resolving branch names and how to configure it.

Branch Resolution Priority

Branch names are resolved in this order (highest priority first):

Level 1: Explicit argument

Pass branch directly to any function that accepts it:

get_branch_info(package = "pipapi", branch = "DEV")

This always wins, regardless of any option settings.

Level 2: Per-package custom branch

Use set_custom_branch() to override specific packages:

set_custom_branch(pipr = "main", pipapi = "DEV_v3")

This sets options(metapip.custom_branch = list(pipr_branch = "main", pipapi_branch = "DEV_v3")) behind the scenes. Now:

get_branch_info(package = "pipapi")  # Uses "DEV_v3"

Level 3: Global default branch

If neither an explicit argument nor a custom branch is set, the global default is used:

get_default_branch()  # Returns "PROD" by default

This comes from options(metapip.default_branch).

Zero-Configuration Defaults

When metapip loads, it ships with sensible defaults:

metapip_default_options <- list(
  metapip.default_branch = "PROD",
  metapip.custom_branch = list(
    pipapi_branch = "DEV",
    pipfaker_branch = "main",
    wbpip_branch = "DEV",
    pipster_branch = "DEV"
  )
)

So out of the box, pipapi uses DEV, pipfaker uses main, and everything else uses PROD.

Viewing Current Configuration

get_default_branch()
get_custom_branch()
get_current_branches()

Modifying Configuration

# Change the global default
set_default_branch("DEV")

# Override specific packages
set_custom_branch(pipdata = "main", pipapi = "DEV_v3")

# Verify
get_current_branches()

Persisting Configuration Across Sessions

The options set by set_default_branch() and set_custom_branch() persist for the current R session only. To make them permanent, add to your .Rprofile:

options(
  metapip.default_branch = "PROD",
  metapip.custom_branch = list(
    pipapi_branch = "DEV",
    wbpip_branch = "DEV",
    pipfaker_branch = "main"
  )
)