Skip to contents

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.

Value

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

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>

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")
#> 
#> ── Set up ──────────────────────────────────────────────────────────────
cli::cli_h2("Create Lesson")
#> 
#> ── Create Lesson ──
#> 
restore_fixture <- sandpaper:::create_test_lesson()
#> → Bootstrapping example lesson
#>  Lesson bootstrapped in 3.159556 secs
#> → Bootstrapping example lesson

res <- getOption("sandpaper.test_fixture")
sandpaper:::check_git_user(res)
cli::cli_h2("Create Remote")
#> 
#> ── Create Remote ──
#> 
rmt <- fs::file_temp(pattern = "REMOTE-")
sandpaper:::setup_local_remote(repo = res, remote = rmt, verbose = FALSE)
#>  Remote set up in 0.01404452 secs
tok <- Sys.time()
cli::cli_alert_info("Elapsed time: {round(tok - tik, 2)} seconds")
#>  Elapsed time: 3.2 seconds
tik <- Sys.time()
cli::cli_h2("Create Worktrees")
#> 
#> ── Create Worktrees ──
#> 
db <- sandpaper:::git_worktree_setup(res, fs::path(res, "site", "built"),
  branch = "md-outputs", remote = "sandpaper-local"
)
#> ::group::Create New Branch
#> Running git checkout --orphan md-outputs
#> Switched to a new branch 'md-outputs'
#> Running git rm -rf --quiet .
#> Running git commit --allow-empty -m 'Initializing md-outputs branch'
#> [md-outputs (root-commit) 529cdb5] Initializing md-outputs branch
#> Running git push sandpaper-local 'HEAD:md-outputs'
#> To /tmp/RtmpHMLZvI/REMOTE-16dd5b8a988a
#>  * [new branch]      HEAD -> md-outputs
#> Running git checkout main
#> Switched to branch 'main'
#> Your branch is up to date with 'sandpaper-local/main'.
#> ::endgroup::
#> ::group::Fetch sandpaper-local/md-outputs
#> Running git remote set-branches sandpaper-local md-outputs
#> Running git fetch sandpaper-local md-outputs
#> From /tmp/RtmpHMLZvI/REMOTE-16dd5b8a988a
#>  * branch            md-outputs -> FETCH_HEAD
#> Running git remote set-branches sandpaper-local '*'
#> ::endgroup::
#> ::group::Add worktree for sandpaper-local/md-outputs in site/built
#> Running git worktree add --track -B md-outputs \
#>   /tmp/RtmpHMLZvI/file16dd52c100b1/lesson-example/site/built \
#>   sandpaper-local/md-outputs
#> Preparing worktree (resetting branch 'md-outputs'; was at 529cdb5)
#> branch 'md-outputs' set up to track 'sandpaper-local/md-outputs'.
#> HEAD is now at 529cdb5 Initializing md-outputs branch
#> ::endgroup::
ds <- sandpaper:::git_worktree_setup(res, fs::path(res, "site", "docs"),
  branch = "gh-pages", remote = "sandpaper-local"
)
#> ::group::Create New Branch
#> Running git checkout --orphan gh-pages
#> Switched to a new branch 'gh-pages'
#> Running git rm -rf --quiet .
#> Running git commit --allow-empty -m 'Initializing gh-pages branch'
#> [gh-pages (root-commit) b9d64ae] Initializing gh-pages branch
#> Running git push sandpaper-local 'HEAD:gh-pages'
#> To /tmp/RtmpHMLZvI/REMOTE-16dd5b8a988a
#>  * [new branch]      HEAD -> gh-pages
#> Running git checkout main
#> Switched to branch 'main'
#> Your branch is up to date with 'sandpaper-local/main'.
#> ::endgroup::
#> ::group::Fetch sandpaper-local/gh-pages
#> Running git remote set-branches sandpaper-local gh-pages
#> Running git fetch sandpaper-local gh-pages
#> From /tmp/RtmpHMLZvI/REMOTE-16dd5b8a988a
#>  * branch            gh-pages   -> FETCH_HEAD
#> Running git remote set-branches sandpaper-local '*'
#> ::endgroup::
#> ::group::Add worktree for sandpaper-local/gh-pages in site/docs
#> Running git worktree add --track -B gh-pages \
#>   /tmp/RtmpHMLZvI/file16dd52c100b1/lesson-example/site/docs \
#>   sandpaper-local/gh-pages
#> Preparing worktree (resetting branch 'gh-pages'; was at b9d64ae)
#> branch 'gh-pages' set up to track 'sandpaper-local/gh-pages'.
#> HEAD is now at b9d64ae Initializing gh-pages branch
#> ::endgroup::
tok <- Sys.time()
cli::cli_alert_info("Elapsed time: {round(tok - tik, 2)} seconds")
#>  Elapsed time: 0.4 seconds
tik <- Sys.time()
cli::cli_h1("Build Lesson into worktrees")
#> 
#> ── Build Lesson into worktrees ─────────────────────────────────────────
build_lesson(res, quiet = TRUE, preview = FALSE)
#> ── Initialising site ───────────────────────────────────────────────────
#> Copying
#> ../../../../../home/runner/work/_temp/Library/pkgdown/BS3/assets/bootstrap-toc.css,
#> ../../../../../home/runner/work/_temp/Library/pkgdown/BS3/assets/bootstrap-toc.js,
#> ../../../../../home/runner/work/_temp/Library/pkgdown/BS3/assets/docsearch.css,
#> ../../../../../home/runner/work/_temp/Library/pkgdown/BS3/assets/docsearch.js,
#> ../../../../../home/runner/work/_temp/Library/pkgdown/BS3/assets/link.svg,
#> ../../../../../home/runner/work/_temp/Library/pkgdown/BS3/assets/pkgdown.css,
#> and
#> ../../../../../home/runner/work/_temp/Library/pkgdown/BS3/assets/pkgdown.js
#> to bootstrap-toc.css, bootstrap-toc.js, docsearch.css, docsearch.js,
#> link.svg, pkgdown.css, and pkgdown.js
#> Copying
#> ../../../../../home/runner/work/_temp/Library/varnish/pkgdown/assets/android-chrome-192x192.png,
#> ../../../../../home/runner/work/_temp/Library/varnish/pkgdown/assets/android-chrome-512x512.png,
#> ../../../../../home/runner/work/_temp/Library/varnish/pkgdown/assets/apple-touch-icon.png,
#> ../../../../../home/runner/work/_temp/Library/varnish/pkgdown/assets/assets/fonts/Mulish-Bold.ttf,
#> ../../../../../home/runner/work/_temp/Library/varnish/pkgdown/assets/assets/fonts/Mulish-Bold.woff,
#> ../../../../../home/runner/work/_temp/Library/varnish/pkgdown/assets/assets/fonts/Mulish-ExtraBold.ttf,
#> ../../../../../home/runner/work/_temp/Library/varnish/pkgdown/assets/assets/fonts/mulish-v5-latin-regular.eot,
#> ../../../../../home/runner/work/_temp/Library/varnish/pkgdown/assets/assets/fonts/mulish-v5-latin-regular.svg,
#> ../../../../../home/runner/work/_temp/Library/varnish/pkgdown/assets/assets/fonts/mulish-v5-latin-regular.ttf,
#> ../../../../../home/runner/work/_temp/Library/varnish/pkgdown/assets/assets/fonts/mulish-v5-latin-regular.woff,
#> ../../../../../home/runner/work/_temp/Library/varnish/pkgdown/assets/assets/fonts/mulish-v5-latin-regular.woff2,
#> ../../../../../home/runner/work/_temp/Library/varnish/pkgdown/assets/assets/fonts/mulish-variablefont_wght.woff,
#> ../../../../../home/runner/work/_temp/Library/varnish/pkgdown/assets/assets/fonts/mulish-variablefont_wght.woff2,
#> ../../../../../home/runner/work/_temp/Library/varnish/pkgdown/assets/assets/images/carpentries-logo-sm.svg,
#> ../../../../../home/runner/work/_temp/Library/varnish/pkgdown/assets/assets/images/carpentries-logo.svg,
#> ../../../../../home/runner/work/_temp/Library/varnish/pkgdown/assets/assets/images/data-logo-sm.svg,
#> ../../../../../home/runner/work/_temp/Library/varnish/pkgdown/assets/assets/images/data-logo.svg,
#> ../../../../../home/runner/work/_temp/Library/varnish/pkgdown/assets/assets/images/dropdown-arrow.svg,
#> …,
#> ../../../../../home/runner/work/_temp/Library/varnish/pkgdown/assets/safari-pinned-tab.svg,
#> and
#> ../../../../../home/runner/work/_temp/Library/varnish/pkgdown/assets/site.webmanifest
#> to android-chrome-192x192.png, android-chrome-512x512.png,
#> apple-touch-icon.png, assets/fonts/Mulish-Bold.ttf,
#> assets/fonts/Mulish-Bold.woff, assets/fonts/Mulish-ExtraBold.ttf,
#> assets/fonts/mulish-v5-latin-regular.eot,
#> assets/fonts/mulish-v5-latin-regular.svg,
#> assets/fonts/mulish-v5-latin-regular.ttf,
#> assets/fonts/mulish-v5-latin-regular.woff,
#> assets/fonts/mulish-v5-latin-regular.woff2,
#> assets/fonts/mulish-variablefont_wght.woff,
#> assets/fonts/mulish-variablefont_wght.woff2,
#> assets/images/carpentries-logo-sm.svg,
#> assets/images/carpentries-logo.svg, assets/images/data-logo-sm.svg,
#> assets/images/data-logo.svg, assets/images/dropdown-arrow.svg, …,
#> safari-pinned-tab.svg, and site.webmanifest
cli::cli_h2("git status: {gert::git_branch(repo = res)}")
#> 
#> ── git status: main ──
#> 
print(gert::git_status(repo = res))
#> # A tibble: 0 × 3
#> # ℹ 3 variables: file <chr>, status <chr>, staged <lgl>
cli::cli_h2('git status: {gert::git_branch(repo = fs::path(res, "site", "built"))}')
#> ── git status: md-outputs ──
#> 
print(gert::git_status(repo = fs::path(res, "site", "built")))
#> # A tibble: 13 × 3
#>    file                status staged
#>    <chr>               <chr>  <lgl> 
#>  1 CODE_OF_CONDUCT.md  new    FALSE 
#>  2 LICENSE.md          new    FALSE 
#>  3 config.yaml         new    FALSE 
#>  4 fig/                new    FALSE 
#>  5 index.md            new    FALSE 
#>  6 instructor-notes.md new    FALSE 
#>  7 introduction.md     new    FALSE 
#>  8 learner-profiles.md new    FALSE 
#>  9 links.md            new    FALSE 
#> 10 md5sum.txt          new    FALSE 
#> 11 reference.md        new    FALSE 
#> 12 renv.lock           new    FALSE 
#> 13 setup.md            new    FALSE 
cli::cli_h2('git status: {gert::git_branch(repo = fs::path(res, "site", "docs"))}')
#> ── git status: gh-pages ──
#> 
print(gert::git_status(repo = fs::path(res, "site", "docs")))
#> # A tibble: 36 × 3
#>    file                       status staged
#>    <chr>                      <chr>  <lgl> 
#>  1 .nojekyll                  new    FALSE 
#>  2 404.html                   new    FALSE 
#>  3 CODE_OF_CONDUCT.html       new    FALSE 
#>  4 LICENSE.html               new    FALSE 
#>  5 aio.html                   new    FALSE 
#>  6 android-chrome-192x192.png new    FALSE 
#>  7 android-chrome-512x512.png new    FALSE 
#>  8 apple-touch-icon.png       new    FALSE 
#>  9 assets/                    new    FALSE 
#> 10 bootstrap-toc.css          new    FALSE 
#> # ℹ 26 more rows
tok <- Sys.time()
cli::cli_alert_info("Elapsed time: {round(tok - tik, 2)} seconds")
#>  Elapsed time: 10.19 seconds
tik <- Sys.time()
cli::cli_h1("Clean Up")
#> 
#> ── Clean Up ────────────────────────────────────────────────────────────
cli::cli_alert_info("object db is an expression that evaluates to {.code {db}}")
#>  object db is an expression that evaluates to `sandpaper:::github_worktree_remove("/tmp/RtmpHMLZvI/file16dd52c100b1/lesson-example/site/built", "/tmp/RtmpHMLZvI/file16dd52c100b1/lesson-example")`
eval(db)
#> Running git worktree remove --force \
#>   /tmp/RtmpHMLZvI/file16dd52c100b1/lesson-example/site/built
#> $status
#> [1] 0
#> 
#> $stdout
#> [1] ""
#> 
#> $stderr
#> [1] ""
#> 
#> $timeout
#> [1] FALSE
#> 
cli::cli_alert_info("object ds is an expression that evaluates to {.code {ds}}")
#>  object ds is an expression that evaluates to `sandpaper:::github_worktree_remove("/tmp/RtmpHMLZvI/file16dd52c100b1/lesson-example/site/docs", "/tmp/RtmpHMLZvI/file16dd52c100b1/lesson-example")`
eval(ds)
#> Running git worktree remove --force \
#>   /tmp/RtmpHMLZvI/file16dd52c100b1/lesson-example/site/docs
#> $status
#> [1] 0
#> 
#> $stdout
#> [1] ""
#> 
#> $stderr
#> [1] ""
#> 
#> $timeout
#> [1] FALSE
#> 
sandpaper:::remove_local_remote(repo = res)
#>  removing 'sandpaper-local' (/tmp/RtmpHMLZvI/REMOTE-16dd5b8a988a)
#> /tmp/RtmpHMLZvI/REMOTE-16dd5b8a988a
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")
#>  Elapsed time: 0.15 seconds