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

Description Usage Arguments Details Value Note Examples

Description

Setup a git worktree for concurrent manipulation of a separate branch

Usage

1
2
3
4
5
6
7
git_worktree_setup(
  path = ".",
  dest_dir,
  branch = "gh-pages",
  remote = "origin",
  throwaway = FALSE
)

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

1
2
3
4
5
6
7
8
9
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

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

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
run_ok <- sandpaper:::has_git() &&
  requireNamespace("withr", quietly = TRUE) &&
  rmarkdown::pandoc_available("2.11")

# 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
if (run_ok) {
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)
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"
)
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")))
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)
}

zkamvar/sandpaper documentation built on Nov. 25, 2021, 1:16 p.m.