More working commands

scribblings/git.scrbl

@@ -73,22 +73,45 @@ Calls @racket[git], displays its result in a compact human-readable form, and re
 
 @section{Branches, checkout, and tags}
 
-@defproc[(git-current-branch) (or/c string? #f)]{Returns the current local branch name, or @racket[#f] for detached HEAD.}
+@defproc[(git-current-branch) (or/c string? #f)]{Returns the current local branch name, or @racket[#f] for detached HEAD. The command form is @racket[(git 'branch-current)].}
 
 @defproc*[([(git-branch) (listof string?)]
            [(git-branch [name string?]) string?])]{Lists local branches, or creates @racket[name] at HEAD.}
 
-@defproc[(git-branch-delete [name string?]) void?]{Deletes a local branch.}
+@defproc[(git-branch-create [name string?] [start-point string? "HEAD"]) string?]{Creates a local branch named @racket[name] at @racket[start-point] and returns @racket[name]. The default start point is the current HEAD, including detached HEAD. The command forms are @racket[(git 'branch-create name)] and @racket[(git 'branch-create name start-point)].}
+
+@defproc[(git-branch-delete [name string?]) void?]{Deletes a local branch. The command form is @racket[(git 'branch '-d name)].}
+
+@defproc[(git-switch [name string?]) (or/c string? #f)]{Switches to an existing local branch and attaches HEAD to that branch. The command form is @racket[(git 'switch name)]. An unknown local branch raises an exception.}
 
 @defproc[(git-checkout [name string?]) (or/c string? #f)]{Checks out a local branch, tag, or commit. A tag or commit produces detached HEAD.}
 
 @defproc[(git-checkout-new [name string?]) string?]{Creates and checks out a new branch.}
 
+@defproc[(git-merge [name string?] [message (or/c string? #f) #f]) (or/c string? #f)]{Merges @racket[name] into the currently attached local branch. An up-to-date merge returns @racket[#f]. A fast-forward returns the new HEAD OID. A clean non-fast-forward merge creates a two-parent merge commit and returns its OID. If @racket[message] is @racket[#f], the merge commit message is @tt{Merge branch 'name'}. Conflicting merges raise an exception before changing HEAD or the worktree. The command forms are @racket[(git 'merge name)] and @racket[(git 'merge name message)].}
+
 @defproc*[([(git-tag) (listof string?)]
            [(git-tag [name string?]) string?])]{Lists tags, or creates a lightweight tag at HEAD and returns its OID.}
 
 @defproc[(git-tag-delete [name string?]) void?]{Deletes a tag.}
 
+@subsection{Recovering a commit made with detached HEAD}
+
+A commit made while HEAD is detached is not attached to a local branch. The following sequence gives the commit a temporary branch name, switches back to @tt{main}, merges the rescued commit, verifies the result, pushes it, and removes the temporary branch:
+
+@racketblock[
+(git 'branch-current) ; => #f
+(git 'branch-create "rescue-readme")
+(git 'switch "main")
+(git 'merge "rescue-readme")
+(git 'status)
+(dgit 'log 5)
+(git 'push)
+(git 'branch '-d "rescue-readme")
+]
+
+The @racket[(dgit 'log 5)] form is the compact Racket equivalent of using a short command-line log for verification: it displays the abbreviated commit OID and summary for the five newest commits.
+
 @section{Log}
 
 @defstruct*[git-log-entry ([id string?] [summary string?] [time integer?])]{Describes one commit returned by @racket[git-log].}
@@ -126,8 +149,12 @@ The following command-like forms are supported directly:
 (git 'add "file.rkt")
 (git 'config "user.name" "Name")
 (git 'commit "message")
+(git 'branch-current)
 (git 'branch)
 (git 'branch "feature")
+(git 'branch-create "rescue" "HEAD")
+(git 'switch "feature")
+(git 'merge "rescue")
 (git 'branch '-d "feature")
 (git 'checkout "main")
 (git 'checkout '-b "feature")