From 5e6764d6fa6e97eb27ff0a1baf722db9ec41eb2a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ma=C3=ABlle=20Salmon?= <maelle.salmon@yahoo.se>
Date: Mon, 23 Mar 2026 13:31:57 +0100
Subject: [PATCH] docs: document how to detect a "detached head"

---
 R/repository.R  |  7 ++++++-
 man/git_repo.Rd | 13 +++++++++++--
 2 files changed, 17 insertions(+), 3 deletions(-)

diff --git a/R/repository.R b/R/repository.R
index e314d59..70a5cf9 100644
--- a/R/repository.R
+++ b/R/repository.R
@@ -5,6 +5,8 @@
 #' * `git_info()` shows basic information about a repository, such as the SHA
 #'   and branch of the current HEAD.
 #'
+#' @section Path:
+#'
 #' For `git_init()` the `path` parameter sets the directory of the git repository
 #' to create. If this directory already exists, it must be empty. If it does
 #' not exist, it is created, along with any intermediate directories that don't
@@ -21,7 +23,7 @@
 #' @family git
 #' @useDynLib gert R_git_repository_init
 #' @inheritParams git_open
-#' @param path the location of the git repository, see details.
+#' @param path the location of the git repository, see the "path" section.
 #' @param bare if true, a Git repository without a working directory is created
 #' @git repository
 #' @return
@@ -68,6 +70,9 @@ git_find <- function(path = '.') {
 #' @export
 #' @rdname git_repo
 #' @useDynLib gert R_git_repository_info
+#' @section Detached head:
+#' If `git_info()$shorthand` is equal to `HEAD`,
+#' it means the repository is in a [detached head state](https://jvns.ca/blog/2023/11/01/confusing-git-terminology/#detached-head-state).
 git_info <- function(repo = '.') {
   repo <- git_open(repo)
   .Call(R_git_repository_info, repo)
diff --git a/man/git_repo.Rd b/man/git_repo.Rd
index e67d8c7..d4515b2 100644
--- a/man/git_repo.Rd
+++ b/man/git_repo.Rd
@@ -14,7 +14,7 @@ git_find(path = ".")
 git_info(repo = ".")
 }
 \arguments{
-\item{path}{the location of the git repository, see details.}
+\item{path}{the location of the git repository, see the "path" section.}
 
 \item{bare}{if true, a Git repository without a working directory is created}
 
@@ -38,7 +38,9 @@ versions of gert may have additional parameters.}
 and branch of the current HEAD.
 }
 }
-\details{
+\section{Path}{
+
+
 For \code{git_init()} the \code{path} parameter sets the directory of the git repository
 to create. If this directory already exists, it must be empty. If it does
 not exist, it is created, along with any intermediate directories that don't
@@ -49,6 +51,13 @@ which to start the search for a git repository. If it is not a git repository
 itself, then its parent directory is consulted, then the parent's parent, and
 so on.
 }
+
+\section{Detached head}{
+
+If \code{git_info()$shorthand} is equal to \code{HEAD},
+it means the repository is in a \href{https://jvns.ca/blog/2023/11/01/confusing-git-terminology/#detached-head-state}{detached head state}.
+}
+
 \examples{
 # directory does not yet exist
 r <- tempfile(pattern = "gert")