bug#63726: time-machine without options does not get the latest commit

[Konrad Hinsen]

Hi Simon,

> What about this patch?

That's a good start! But I didn't quite understand what "as defined by the 
previous
+@dfn{channels} file" means, so I did some more research and some more
rewriting, and came up with the attached patch. That one is clear for
me, but maybe not for others...

In the course of this research, I noticed that channel files are used in
Guix in two varieties for rather different purposes, but this doesn't
seem to be explained anywhere. "guix describe -f channels" produces
channel files with a pinned commit for each repository. That's what we
usually give to time-machine. That feature of channel files seems even
undocumented. The chapter on channels discusses the channel files we
typically use with "guix pull", and which refer to a branch and thus its
last commit, rather than to a pinned commit.

Cheers,
  Konrad.

>From cbe372191a2daea7b62d8558422f08bc6ed0e047 Mon Sep 17 00:00:00 2001
From: Konrad Hinsen <konrad.hinsen@fastmail.net>
Date: Thu, 1 Jun 2023 16:55:33 +0200
Subject: [PATCH] doc: Reword guix time-machine without option.

* doc/guix.texi (Invoking guix time-machine): Reword the behaviour in the
absence of any option.
---
 doc/guix.texi | 19 ++++++++++++++-----
 1 file changed, 14 insertions(+), 5 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 7f8d8d66e9..e4daffe4dd 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -4959,16 +4959,25 @@ Invoking guix time-machine
 @xref{Channels} for more information.
 @end table
 
-As for @command{guix pull}, the absence of any options means that the
-latest commit on the master branch will be used.  The command
+In the absence of any options, the target revision will be determined as
+for @command{guix pull}, i.e. from the user's
+@file{~/.config/guix/channels.scm} file, or, if no such file exists,
+from the system-wide @file{/etc/guix/channels.scm} file, or, if that
+file does not exist either, from the built-in default channels specified
+in the @code{%default-channels} variable.  Note that these three
+fallbacks are usually channel definitions pointing to @i{branches} in
+git repositories, rather then to specific @i{commits}, as the channel
+definitions produced by @command{guix describe} do. A branch-based
+channel definition refers to the latest commit on that branch. The
+command
 
 @example
 guix time-machine -- build hello
 @end example
 
-will thus build the package @code{hello} as defined in the master branch,
-which is in general a newer revision of Guix than you have installed.
-Time travel works in both directions!
+will thus build the package @code{hello} as defined by the current state
+of the default channels. In general, it builds a @i{newer} revision of
+Guix than you have installed.  Time travel works in both directions!
 
 Note that @command{guix time-machine} can trigger builds of channels and
 their dependencies, and these are controlled by the standard build
-- 
2.40.1