From 12f3267fa9f72eaaa645bf5f3ce79003f153c069 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ma=C3=ABlle=20Salmon?= Date: Mon, 27 Apr 2026 13:58:55 +0200 Subject: [PATCH 1/2] docs: add example to the rebase manual page --- R/rebase.R | 55 +++++++++++++++++++++++++++++++-- man/git_rebase.Rd | 77 +++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 117 insertions(+), 15 deletions(-) diff --git a/R/rebase.R b/R/rebase.R index 114fd6b..c3dcfb8 100644 --- a/R/rebase.R +++ b/R/rebase.R @@ -3,12 +3,18 @@ #' @description #' * `git_cherry_pick()` applies the changes from a given commit (from another branch) #' onto the current branch. -#' *`git_rebase_commit()` resets the branch to the state of another branch (upstream) +#' +#' * `git_rebase_commit()` resets the branch to the state of another branch (upstream) #' and then re-applies your local changes by cherry-picking each of your local #' commits onto the upstream commit history. -#' *`git_rebase_list()` shows your local commits that are missing from the `upstream` +#' +#' * `git_rebase_list()` shows your local commits that are missing from the `upstream` #' history, and if they conflict with upstream changes. #' +#' * `git_ahead_behind()` returns a list containing the number of commits ahead and behind +#' comparing `upstream` to `ref`, +#' and the HEAD for respectively the `ref` and `upstream`. +#' #' #' @details #' To find if your local commits are missing from `upstream`, @@ -20,6 +26,51 @@ #' "rebasing" state. If conflicts arise, `git_rebase_commit()` will raise an error #' without making changes. #' +#' @examplesIf interactive() +#' # Cherry-picking +#' repo <- tempfile() +#' gert::git_init(path = repo) +#' writeLines("hello", file.path(repo, 'hello.txt')) +#' git_add('hello.txt', repo = repo) +#' first_commit <- git_commit( +#' "First commit", +#' author = "Jane Doe ", +#' repo = repo +#' ) +#' # Create a feature branch with a new commit +#' mainbranch <- gert::git_branch(repo = repo) +#' git_branch_create('feature', repo = repo) +#' write.csv(mtcars, file.path(repo, 'mtcars.csv')) +#' git_add('mtcars.csv', repo = repo) +#' commit <- git_commit( +#' "Added mtcars.csv file", +#' author = "Jane Doe ", +#' repo = repo +#' ) +#' # Cherry pick the commit onto main +#' git_branch_switch(mainbranch, repo = repo) +#' git_log(repo = repo) +#' git_cherry_pick(commit, repo = repo) +#' git_log(repo = repo) +#' +#' # Clean up +#' unlink(repo, recursive = TRUE) +#' +#' # git ahead/behind and git_rebase_list +#' repo <- file.path(tempdir(), 'gert') +#' if (!file.exists(repo)) { +#' git_clone('https://github.com/r-lib/gert', path = repo) +#'} +#' # Drop some commits, and fast-forward them back +#' git_reset_hard('HEAD~5', repo = repo) +#' file.create(file.path(repo, "bla")) +#' git_add("bla", repo = repo) +#' git_commit("add bla", repo = repo) +#' git_ahead_behind(repo = repo) +#' git_rebase_list(repo = repo) +#' +#' # Clean up +#' unlink(repo, recursive = TRUE) #' @export #' @rdname git_rebase #' @name git_rebase diff --git a/man/git_rebase.Rd b/man/git_rebase.Rd index 1908d97..ca27ed7 100644 --- a/man/git_rebase.Rd +++ b/man/git_rebase.Rd @@ -35,11 +35,14 @@ versions of gert may have additional parameters.} \itemize{ \item \code{git_cherry_pick()} applies the changes from a given commit (from another branch) onto the current branch. -*\code{git_rebase_commit()} resets the branch to the state of another branch (upstream) +\item \code{git_rebase_commit()} resets the branch to the state of another branch (upstream) and then re-applies your local changes by cherry-picking each of your local commits onto the upstream commit history. -*\code{git_rebase_list()} shows your local commits that are missing from the \code{upstream} +\item \code{git_rebase_list()} shows your local commits that are missing from the \code{upstream} history, and if they conflict with upstream changes. +\item \code{git_ahead_behind()} returns a list containing the number of commits ahead and behind +comparing \code{upstream} to \code{ref}, +and the HEAD for respectively the \code{ref} and \code{upstream}. } } \details{ @@ -52,23 +55,71 @@ Gert only support a clean rebase; it never leaves the repository in unfinished "rebasing" state. If conflicts arise, \code{git_rebase_commit()} will raise an error without making changes. } +\examples{ +\dontshow{if (interactive()) withAutoprint(\{ # examplesIf} +# Cherry-picking +repo <- tempfile() +gert::git_init(path = repo) +writeLines("hello", file.path(repo, 'hello.txt')) +git_add('hello.txt', repo = repo) +first_commit <- git_commit( + "First commit", + author = "Jane Doe ", + repo = repo + ) +# Create a feature branch with a new commit +mainbranch <- gert::git_branch(repo = repo) +git_branch_create('feature', repo = repo) +write.csv(mtcars, file.path(repo, 'mtcars.csv')) +git_add('mtcars.csv', repo = repo) +commit <- git_commit( + "Added mtcars.csv file", + author = "Jane Doe ", + repo = repo +) +# Cherry pick the commit onto main +git_branch_switch(mainbranch, repo = repo) +git_log(repo = repo) +git_cherry_pick(commit, repo = repo) +git_log(repo = repo) + +# Clean up +unlink(repo, recursive = TRUE) + +# git ahead/behind and git_rebase_list +repo <- file.path(tempdir(), 'gert') +if (!file.exists(repo)) { + git_clone('https://github.com/r-lib/gert', path = repo) +} +# Drop some commits, and fast-forward them back +git_reset_hard('HEAD~5', repo = repo) +file.create(file.path(repo, "bla")) +git_add("bla", repo = repo) +git_commit("add bla", repo = repo) +git_ahead_behind(repo = repo) +git_rebase_list(repo = repo) + +# Clean up +unlink(repo, recursive = TRUE) +\dontshow{\}) # examplesIf} +} \seealso{ -Other git: +Other git: \code{\link{git_archive}}, -\code{\link[=git_branch]{git_branch()}}, -\code{\link[=git_commit]{git_commit()}}, -\code{\link[=git_config]{git_config()}}, -\code{\link[=git_diff]{git_diff()}}, -\code{\link[=git_fetch]{git_fetch()}}, +\code{\link{git_branch}()}, +\code{\link{git_commit}()}, +\code{\link{git_config}()}, +\code{\link{git_diff}()}, +\code{\link{git_fetch}()}, \code{\link{git_history}}, \code{\link{git_ignore}}, -\code{\link[=git_merge]{git_merge()}}, +\code{\link{git_merge}()}, \code{\link{git_remote}}, \code{\link{git_repo}}, -\code{\link[=git_reset]{git_reset()}}, -\code{\link[=git_restore]{git_restore()}}, -\code{\link[=git_revert]{git_revert()}}, -\code{\link[=git_signature]{git_signature()}}, +\code{\link{git_reset}()}, +\code{\link{git_restore}()}, +\code{\link{git_revert}()}, +\code{\link{git_signature}()}, \code{\link{git_stash}}, \code{\link{git_tag}}, \code{\link{git_worktree}} From b2c5300e4599a1dcd0609b183a5fa2f32bb14cc6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ma=C3=ABlle=20Salmon?= Date: Mon, 1 Jun 2026 14:50:45 +0200 Subject: [PATCH 2/2] docs: run examples on CI --- DESCRIPTION | 2 +- R/commit.R | 2 +- R/config.R | 2 +- R/restore.R | 2 +- man/git_restore.Rd | 2 +- man/git_revert.Rd | 2 +- man/user_is_configured.Rd | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 9319578..0293ad7 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -32,6 +32,6 @@ VignetteBuilder: knitr Encoding: UTF-8 Roxygen: list(markdown = TRUE) -RoxygenNote: 7.3.3.9000 SystemRequirements: libgit2 (>= 1.0): libgit2-devel (rpm) or libgit2-dev (deb) Language: en-US +Config/roxygen2/version: 8.0.0.9000 diff --git a/R/commit.R b/R/commit.R index e8676f2..4c806e8 100644 --- a/R/commit.R +++ b/R/commit.R @@ -273,7 +273,7 @@ git_stat_files <- function(files, ref = "HEAD", max = NULL, repo = '.') { #' @param ... parameters passed to `git_commit` such as `message` or `author` #' @return The SHA of the new revert commit (invisibly), or `NULL` when #' `commit = FALSE`. -#' @examplesIf interactive() +#' @examplesIf interactive() || isTRUE(as.logical(Sys.getenv("CI", "false"))) #' repo <- file.path(tempdir(), "myrepo") #' git_init(repo) #' diff --git a/R/config.R b/R/config.R index fbdb2ab..42899b2 100644 --- a/R/config.R +++ b/R/config.R @@ -198,7 +198,7 @@ global_user_is_configured <- function() { #' `FALSE` otherwise. #' #' @export -#' @examplesIf interactive() +#' @examplesIf interactive() || isTRUE(as.logical(Sys.getenv("CI", "false"))) #' user_is_configured() user_is_configured <- function(repo = ".") { user_name_exists <- !is.null(git_config_get("user.name", repo = repo)) diff --git a/R/restore.R b/R/restore.R index e003d29..5094746 100644 --- a/R/restore.R +++ b/R/restore.R @@ -16,7 +16,7 @@ #' @param ref revision string with a branch/tag/commit to restore from. #' Defaults to `"HEAD"`. #' @return Invisibly, the [git_status()] after restoring. -#' @examplesIf interactive() +#' @examplesIf interactive() || isTRUE(as.logical(Sys.getenv("CI", "false"))) #' repo <- file.path(tempdir(), "myrepo") #' git_init(repo) #' diff --git a/man/git_restore.Rd b/man/git_restore.Rd index 21cb804..d5aab2a 100644 --- a/man/git_restore.Rd +++ b/man/git_restore.Rd @@ -30,7 +30,7 @@ current HEAD. By default restores from HEAD, discarding any local modifications. } \examples{ -\dontshow{if (interactive()) withAutoprint(\{ # examplesIf} +\dontshow{if (interactive() || isTRUE(as.logical(Sys.getenv("CI", "false")))) withAutoprint(\{ # examplesIf} repo <- file.path(tempdir(), "myrepo") git_init(repo) diff --git a/man/git_revert.Rd b/man/git_revert.Rd index 713685d..ecbfcb1 100644 --- a/man/git_revert.Rd +++ b/man/git_revert.Rd @@ -34,7 +34,7 @@ to only stage the reverted changes without committing, leaving you free to amend or combine them before calling \code{\link[=git_commit]{git_commit()}}. } \examples{ -\dontshow{if (interactive()) withAutoprint(\{ # examplesIf} +\dontshow{if (interactive() || isTRUE(as.logical(Sys.getenv("CI", "false")))) withAutoprint(\{ # examplesIf} repo <- file.path(tempdir(), "myrepo") git_init(repo) diff --git a/man/user_is_configured.Rd b/man/user_is_configured.Rd index 37c0ff7..7cf0438 100644 --- a/man/user_is_configured.Rd +++ b/man/user_is_configured.Rd @@ -19,7 +19,7 @@ configured, in order to make commits. \code{user_is_configured()} makes no distinction between local or global user config. } \examples{ -\dontshow{if (interactive()) withAutoprint(\{ # examplesIf} +\dontshow{if (interactive() || isTRUE(as.logical(Sys.getenv("CI", "false")))) withAutoprint(\{ # examplesIf} user_is_configured() \dontshow{\}) # examplesIf} }