githug (version 0.0.0.9000)

git-revision: Identify commits like a human

Description

Retrieve the SHA-1 for a specific commit via a human-friendly description, like

• HEAD: the most recent commit and the one that will be parent to the next commit.
• master@{1 month ago}: the tip commit of the master branch this time last month
• bug-fix: the tip commit of the bug-fix branch
• feature^: parent of the tip commit of the feature branch
• master~2: grandparent of the tip commit of the master branch
• 8675309: commit with 8675309 as leading substring of SHA-1

Convenience wrapper around git2r::revparse_single(), which implements functionality from git rev-parse.

Usage

git_revision(rev = "HEAD", repo = ".")
git_revision_exists(rev, repo = ".")

Arguments

rev

Target commit, as a revision string, e.g. HEAD^, branchname, SHA-1 or a leading substring thereof.

repo

Path to a Git repo. If unspecified, current working directory is checked to see if it is or is inside a Git repo.

Value

SHA of the commit. The when attribute holds the commit time as POSIXct. An excerpt of the commit message is in the msg_start attribute.

git_revision

If called with no arguments, this returns SHA for HEAD of repo associated with current working directory.

git_revision_exists

Tests if rev can be resolved to a specific commit.

References

Revision Selection from the Pro Git book by Scott Chacon and Ben Straub

Specifying revisions section of the git-rev-parse man page

Examples

repo <- git_init(tempfile("githug-revisions-"))
owd <- setwd(repo)

## no commits --> HEAD cannot be resolved
git_revision_exists("HEAD")
## Not run: 
# git_revision()
# ## End(Not run)

## commit and ... now HEAD exists
write("Well, we're not in the middle of nowhere,", "nowhere.txt")
git_commit(all = TRUE, message = "1ouise: not in the middle of nowhere")
git_revision()
git_revision_exists("HEAD")

## make a new commit then ask for parent of HEAD
write("but we can see it from here.", "nowhere.txt", append = TRUE)
git_commit(all = TRUE, message = "louise: but can see it")
git_revision("HEAD^")

## create a new branch and find out what it points at
git_switch("newbranch", create = TRUE)
git_revision("newbranch")

setwd(owd)