Setup a git worktree for concurrent manipulation of a separate branch
Source:R/utils-git.R
git_worktree.RdSetup 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 toFALSE, 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.137434 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.01386094 secs
tok <- Sys.time()
cli::cli_alert_info("Elapsed time: {round(tok - tik, 2)} seconds")
#> ℹ Elapsed time: 3.18 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) 2a258d9] Initializing md-outputs branch
#> Running git push sandpaper-local 'HEAD:md-outputs'
#> To /tmp/Rtmpy58M2t/REMOTE-18767e2d10d7
#> * [new branch] HEAD -> md-outputs
#> Running git checkout main
#> Your branch is up to date with 'sandpaper-local/main'.
#> Switched to branch '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/Rtmpy58M2t/REMOTE-18767e2d10d7
#> * 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/Rtmpy58M2t/file187619ce81a1/lesson-example/site/built \
#> sandpaper-local/md-outputs
#> Preparing worktree (resetting branch 'md-outputs'; was at 2a258d9)
#> branch 'md-outputs' set up to track 'sandpaper-local/md-outputs'.
#> HEAD is now at 2a258d9 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) c7183b4] Initializing gh-pages branch
#> Running git push sandpaper-local 'HEAD:gh-pages'
#> To /tmp/Rtmpy58M2t/REMOTE-18767e2d10d7
#> * [new branch] HEAD -> gh-pages
#> Running git checkout main
#> Your branch is up to date with 'sandpaper-local/main'.
#> Switched to branch '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/Rtmpy58M2t/REMOTE-18767e2d10d7
#> * 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/Rtmpy58M2t/file187619ce81a1/lesson-example/site/docs \
#> sandpaper-local/gh-pages
#> Preparing worktree (resetting branch 'gh-pages'; was at c7183b4)
#> branch 'gh-pages' set up to track 'sandpaper-local/gh-pages'.
#> HEAD is now at c7183b4 Initializing gh-pages branch
#> ::endgroup::
tok <- Sys.time()
cli::cli_alert_info("Elapsed time: {round(tok - tik, 2)} seconds")
#> ℹ Elapsed time: 0.38 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.09 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/Rtmpy58M2t/file187619ce81a1/lesson-example/site/built", "/tmp/Rtmpy58M2t/file187619ce81a1/lesson-example")`
eval(db)
#> Running git worktree remove --force \
#> /tmp/Rtmpy58M2t/file187619ce81a1/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/Rtmpy58M2t/file187619ce81a1/lesson-example/site/docs", "/tmp/Rtmpy58M2t/file187619ce81a1/lesson-example")`
eval(ds)
#> Running git worktree remove --force \
#> /tmp/Rtmpy58M2t/file187619ce81a1/lesson-example/site/docs
#> $status
#> [1] 0
#>
#> $stdout
#> [1] ""
#>
#> $stderr
#> [1] ""
#>
#> $timeout
#> [1] FALSE
#>
sandpaper:::remove_local_remote(repo = res)
#> ℹ removing 'sandpaper-local' (/tmp/Rtmpy58M2t/REMOTE-18767e2d10d7)
#> /tmp/Rtmpy58M2t/REMOTE-18767e2d10d7
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.16 seconds