revset, templater: deprecate git_head() and git_refs() functions

CHANGELOG.md

@@ -20,6 +20,11 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Deprecations
 
+* The `git_head()` and `git_refs()` functions will be removed from revsets and
+  templates. `git_head()` should point to the `first_parent(@)` revision in
+  colocated repositories. `git_refs()` can be approximated as
+  `remote_bookmarks(remote=glob:*) | tags()`.
+
 ### New features
 
 * Updated the executable bit representation in the local working copy to allow

cli/src/commands/git/colocation.rs

@@ -15,6 +15,7 @@
 use std::io::ErrorKind;
 use std::io::Write as _;
 
+use itertools::Itertools as _;
 use jj_lib::commit::Commit;
 use jj_lib::file_util::IoResultExt as _;
 use jj_lib::git;
@@ -98,20 +99,40 @@ fn cmd_git_colocation_status(
     // Make sure that the workspace supports git colocation commands
     workspace_supports_git_colocation_commands(&workspace_command)?;
 
-    let is_colocated =
-        is_colocated_git_workspace(workspace_command.workspace(), workspace_command.repo());
+    let repo = workspace_command.repo();
+    let is_colocated = is_colocated_git_workspace(workspace_command.workspace(), repo);
+    let git_head = repo.view().git_head();
 
     if is_colocated {
         writeln!(ui.stdout(), "Workspace is currently colocated with Git.")?;
-        writeln!(
-            ui.hint_default(),
-            "To disable colocation, run: `jj git colocation disable`"
-        )?;
     } else {
         writeln!(
             ui.stdout(),
             "Workspace is currently not colocated with Git."
         )?;
+    }
+
+    // git_head should be absent in non-colocated workspace, but print the
+    // actual status so we can debug problems.
+    writeln!(
+        ui.stdout(),
+        "Last imported/exported Git HEAD: {}",
+        git_head
+            .as_merge()
+            .iter()
+            .map(|maybe_id| match maybe_id {
+                Some(id) => id.to_string(),
+                None => "(none)".to_owned(),
+            })
+            .join(", ")
+    )?;
+
+    if is_colocated {
+        writeln!(
+            ui.hint_default(),
+            "To disable colocation, run: `jj git colocation disable`"
+        )?;
+    } else {
         writeln!(
             ui.hint_default(),
             "To enable colocation, run: `jj git colocation enable`"

cli/src/commit_templater.rs

@@ -1162,18 +1162,28 @@ fn builtin_commit_methods<'repo>() -> CommitTemplateBuildMethodFnMap<'repo, Comm
             Ok(out_property.into_dyn_wrapped())
         },
     );
+    // TODO: Remove in jj 0.43+
     map.insert(
         "git_refs",
-        |language, _diagnostics, _build_ctx, self_property, function| {
+        |language, diagnostics, _build_ctx, self_property, function| {
+            diagnostics.add_warning(TemplateParseError::expression(
+                "commit.git_refs() is deprecated; use .remote_bookmarks()/tags() instead",
+                function.name_span,
+            ));
             function.expect_no_arguments()?;
             let index = language.keyword_cache.git_refs_index(language.repo).clone();
             let out_property = self_property.map(move |commit| index.get(commit.id()).to_vec());
             Ok(out_property.into_dyn_wrapped())
         },
     );
+    // TODO: Remove in jj 0.43+
     map.insert(
         "git_head",
-        |language, _diagnostics, _build_ctx, self_property, function| {
+        |language, diagnostics, _build_ctx, self_property, function| {
+            diagnostics.add_warning(TemplateParseError::expression(
+                "commit.git_head() is deprecated; use .contained_in('first_parent(@)') instead",
+                function.name_span,
+            ));
             function.expect_no_arguments()?;
             let repo = language.repo;
             let out_property = self_property.map(|commit| {

cli/src/config/colors.toml

@@ -31,6 +31,7 @@
 "remote_bookmarks" = "magenta"
 "tag" = "magenta"
 "tags" = "magenta"
+# TODO: remove git_refs and git_head (but not git_ref) in jj 0.43+
 "git_ref" = "green"
 "git_refs" = "green"
 "git_head" = "green"

cli/src/config/templates.toml

@@ -173,7 +173,6 @@ if(commit.root(),
       commit.bookmarks(),
       commit.tags(),
       commit.working_copies(),
-      if(commit.git_head(), label("git_head", "git_head()")),
       format_short_commit_id(commit.commit_id()),
       if(commit.conflict(), label("conflict", "conflict")),
       if(config("ui.show-cryptographic-signatures").as_boolean(),
@@ -485,7 +484,6 @@ separate(" ",
   commit.bookmarks(),
   commit.tags(),
   commit.working_copies(),
-  if(commit.git_head(), label("git_head", "git_head()")),
   format_short_commit_id(commit.commit_id()),
   if(commit.conflict(), label("conflict", "conflict")),
   if(config("ui.show-cryptographic-signatures").as_boolean(),
@@ -511,7 +509,6 @@ separate(" ",
   )),
   commit.tags().map(|tag| concat("tag-", hash(tag.name()).substr(0, 4))),
   commit.working_copies(),
-  if(commit.git_head(), label("git_head", "git_head()")),
   format_short_commit_id(commit.commit_id()),
   if(commit.conflict(), label("conflict", "conflict")),
   if(config("ui.show-cryptographic-signatures").as_boolean(),

cli/tests/test_commit_template.rs

@@ -795,13 +795,22 @@ fn test_log_git_head() {
     ○  true
     ◆  false
     [EOF]
+    ------- stderr -------
+    Warning: In template expression
+     --> 1:1
+      |
+    1 | git_head
+      | ^------^
+      |
+      = commit.git_head() is deprecated; use .contained_in('first_parent(@)') instead
+    [EOF]
     ");
 
     let output = work_dir.run_jj(["log", "--color=always"]);
     insta::assert_snapshot!(output, @r"
     @  rlvkpnrz [38;5;[email protected] 2001-02-03 08:05:09 687fadfd
     │  initial
-    ○  qpvuntsm [38;5;[email protected] 2001-02-03 08:05:07 git_head() e8849ae1
+    ○  qpvuntsm [38;5;[email protected] 2001-02-03 08:05:07 e8849ae1
     │  (empty) (no description set)
     ◆  zzzzzzzz root() 00000000
     [EOF]