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

While these two are stored in view objects, we intentionally ignore them when
undoing. This means that these fields don't have to be tracked by
view/operation. I think we can move them away to GitBackend-specific data.

We could provide git_head()/git_refs() that load data from GitBackend, but I
don't think these template/revset functions are useful. I've never used them
except for the git_head() template function, and its use case was to see whether
the repository is colocated or not.

Author: yuja

CHANGELOG.md

@@ -17,6 +17,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 `@-` 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/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('@-') 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/tests/test_commit_template.rs

@@ -795,6 +795,15 @@ 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('@-') instead
+    [EOF]
     ");
 
     let output = work_dir.run_jj(["log", "--color=always"]);

docs/revsets.md

@@ -286,11 +286,6 @@ revsets (expressions) as arguments.
   tags `v123` and `rev1` but not the tag `v2`. If a tag is
   in a conflicted state, all its possible targets are included.
 
-* `git_refs()`:  All Git ref targets as of the last import. If a Git ref
-  is in a conflicted state, all its possible targets are included.
-
-* `git_head()`: The Git `HEAD` target as of the last import.
-
 * `visible_heads()`: All visible heads (same as `heads(all())` if no hidden
   revisions are mentioned).
 

docs/templates.md

@@ -161,8 +161,6 @@ This type cannot be printed. The following methods are defined.
   local one.
 * `.local_tags() -> List<CommitRef>`: All local tags pointing to the commit.
 * `.remote_tags() -> List<CommitRef>`: All remote tags pointing to the commit.
-* `.git_refs() -> List<CommitRef>`
-* `.git_head() -> Boolean`: True for the Git `HEAD` commit.
 * `.divergent() -> Boolean`: True if the commit's change id corresponds to multiple
   visible commits.
 * `.hidden() -> Boolean`: True if the commit is not visible (a.k.a. abandoned).

lib/src/revset.rs

@@ -932,11 +932,21 @@ static BUILTIN_FUNCTION_MAP: LazyLock<HashMap<&str, RevsetFunction>> = LazyLock:
         };
         Ok(RevsetExpression::tags(expr))
     });
-    map.insert("git_refs", |_diagnostics, function, _context| {
+    // TODO: Remove in jj 0.43+
+    map.insert("git_refs", |diagnostics, function, _context| {
+        diagnostics.add_warning(RevsetParseError::expression(
+            "git_refs() is deprecated; use remote_bookmarks()/tags() instead",
+            function.name_span,
+        ));
         function.expect_no_arguments()?;
         Ok(RevsetExpression::git_refs())
     });
-    map.insert("git_head", |_diagnostics, function, _context| {
+    // TODO: Remove in jj 0.43+
+    map.insert("git_head", |diagnostics, function, _context| {
+        diagnostics.add_warning(RevsetParseError::expression(
+            "git_head() is deprecated; use @- instead",
+            function.name_span,
+        ));
         function.expect_no_arguments()?;
         Ok(RevsetExpression::git_head())
     });