git_worktree: Setup a git worktree for concurrent manipulation of a...

In zkamvar/sandpaper: Create and Curate Carpentries Lessons

Setup a git worktree for concurrent manipulation of a separate branch

Description

Setup a git worktree for concurrent manipulation of a separate branch

Usage

git_worktree_setup(
  path = ".",
  dest_dir,
  branch = "gh-pages",
  remote = "origin",
  throwaway = FALSE
)

github_worktree_commit(dir, commit_message, remote, branch)

github_worktree_remove(dir, home = NULL)

Arguments

path	path to the repository
dest_dir	path to the destination directory to contain the work tree
branch	the branch associated with the work tree (default: gh-pages)
remote	the remote name (default: origin)
throwaway	if TRUE, the worktree created is in a detached HEAD state from from the remote branch and will not create a new branch in your repository. Defaults to FALSE, which will create the branch from upstream.

Details

This function is used in continuous integration settings where we want to push derived outputs to non-main branches in our repository. We use this to populate the markdown and HTML outputs from the lesson so that we don't have to rebuild the lesson from scratch every time.

The logic behind this looks like

worktree setup
[IF BRANCH DOES NOT EXIST]
  git checkout --orphan <branch>
  git rm -rf --quiet .
  git commit --allow-empty -m
  git push remote HEAD:<branch>
  git checkout -
git fetch <remote> +refs/heads/<branch>:refs/remotes/<remote>/<branch>
git worktree add --track -B <branch> /path/to/dir <remote>/<branch>

Value

an expression() that calls ⁠git worktree remove⁠ on the worktree when evaluated.

Note

git_worktree_setup() has been modified from the logic in pkgdown::deploy_to_branch(), by Hadley Wickham.

github_worktree_commit(): Modified from pkgdown:::github_push by Hadley Wickham

github_worktree_remove(): Modified from pkgdown:::github_worktree_remove by Hadley Wickham

Examples

# Use Worktrees to deploy a lesson -----------------------------------------
# This example is a bit inovlved, but it is effectively what we do inside of
# the `ci_deploy()` function (after setting up the lesson).
#
# The setup phase will create a new lesson and a corresponding remote (self
# contained, no GitHub authentication required).
#
# The worktrees will be created for both the markdown and HTML outputs on the
# branches "md-outputs" and "gh-pages", respectively.
#
# After the worktrees are created, we will build the lesson into the
# worktrees and display the output of `git_status()` for each of the three
# branches: "main", "md-outputs", and "gh-pages"
#
# During the clean up phase, the output of `git_worktree_setup()` is
# evaluated
tik <- Sys.time()
cli::cli_h1("Set up")
cli::cli_h2("Create Lesson")
restore_fixture <- sandpaper:::create_test_lesson()
res <- getOption("sandpaper.test_fixture")
sandpaper:::check_git_user(res)
cli::cli_h2("Create Remote")
rmt <- fs::file_temp(pattern = "REMOTE-")
sandpaper:::setup_local_remote(repo = res, remote = rmt, verbose = FALSE)
tok <- Sys.time()
cli::cli_alert_info("Elapsed time: {round(tok - tik, 2)} seconds")
tik <- Sys.time()
cli::cli_h2("Create Worktrees")
db <- sandpaper:::git_worktree_setup(res, fs::path(res, "site", "built"),
  branch = "md-outputs", remote = "sandpaper-local"
)
ds <- sandpaper:::git_worktree_setup(res, fs::path(res, "site", "docs"),
  branch = "gh-pages", remote = "sandpaper-local"
)
tok <- Sys.time()
cli::cli_alert_info("Elapsed time: {round(tok - tik, 2)} seconds")
tik <- Sys.time()
cli::cli_h1("Build Lesson into worktrees")
build_lesson(res, quiet = TRUE, preview = FALSE)
cli::cli_h2("git status: {gert::git_branch(repo = res)}")
print(gert::git_status(repo = res))
cli::cli_h2('git status: {gert::git_branch(repo = fs::path(res, "site", "built"))}')
print(gert::git_status(repo = fs::path(res, "site", "built")))
cli::cli_h2('git status: {gert::git_branch(repo = fs::path(res, "site", "docs"))}')
print(gert::git_status(repo = fs::path(res, "site", "docs")))
tok <- Sys.time()
cli::cli_alert_info("Elapsed time: {round(tok - tik, 2)} seconds")
tik <- Sys.time()
cli::cli_h1("Clean Up")
cli::cli_alert_info("object db is an expression that evaluates to {.code {db}}")
eval(db)
cli::cli_alert_info("object ds is an expression that evaluates to {.code {ds}}")
eval(ds)
sandpaper:::remove_local_remote(repo = res)
sandpaper:::reset_git_user(res)
# remove the test fixture and report
tryCatch(fs::dir_delete(res), error = function() FALSE)
tok <- Sys.time()
cli::cli_alert_info("Elapsed time: {round(tok - tik, 2)} seconds")

zkamvar/sandpaper documentation built on Feb. 2, 2025, 5:17 p.m.