[9.0.0] Support checking out the repo's default branch in git_repository/new_git_repository rule (#27701)

The `git_repository` and `new_git_repository` rules currently require
not only the remote repository URI to be specified but also either the
branch, tag or revision (commit) to check out. This PR removes the
latter requirement. If no branch, tag or revision are specified, the
repo's default branch will be checked out.

The main reason for introducing this proposed change, is because I
noticed certain Bazel rules already generate `git_repository` targets
from git URIs or other git repo specs that might not have a branch, tag
or revision specified. These rules then typically default to a branch
name of `master`, which is not correct in general. This change will
allow those rules to simply omit the branch, tag and revision from the
generated `git_repository` targets, to check out the repo's default
branch.

An alternative, more explicit, interface for specifying that the default
branch is to be checked out, would have been to add an optional boolean
`default_branch` attribute to the `git_repository` and
`new_git_repository` rules. The presence of that attribute would be
mutually exclusive with the presence of `branch`, `tag` and `commit`.
Let me know if that interface is preferable.

Addresses issue #27610.

Closes #27611.

PiperOrigin-RevId: 833710273
Change-Id: I7bc18efcbcfcaba61bf27052fecceb50336d2eb3

Commit
ee3af97

Co-authored-by: Pieter Agten <pieter.agten@gmail.com>

Author: bazel-io

src/test/java/com/google/devtools/build/lib/blackbox/tests/workspace/GitRepositoryBlackBoxTest.java

@@ -38,9 +38,10 @@
  * classes.
  *
  * <p>1. We are creating some git repository with the preset contents, which will be used for
- * fetching contents for the test. We plan to fetch contents specifying either commit hash, tag, or
- * branch. For all test variants, we are creating the same repository, as the same HEAD commit is
- * marked with a tag, and can be addressed with commit hash, main branch, and tag name.
+ * fetching contents for the test. We plan to fetch contents specifying either commit hash, tag,
+ * specific branch or default branch. For all test variants, we are creating the same repository, as
+ * the same HEAD commit is marked with a tag, and can be addressed with commit hash, main branch,
+ * and tag name.
  *
  * <p>2. The contents of the git repository working tree is generated by {@link
  * RepoWithRuleWritingTextGenerator}. We pass some certain text to that generator; that exact text
@@ -152,6 +153,38 @@ public void testCloneAtMain() throws Exception {
     WorkspaceTestUtils.assertLinesExactly(outPath, HELLO_FROM_EXTERNAL_REPOSITORY);
   }
 
+  /**
+   * Tests usage of new_git_repository workspace rule without a "tag", "commit" or "branch"
+   * attribute, which means the repository's default branch is to be checked out. Please see the
+   * general approach description in the class javadoc comment.
+   */
+  @Test
+  public void testCloneAtDefaultBranch() throws Exception {
+    Path repo = context().getTmpDir().resolve("ext_repo");
+    setupGitRepository(context(), repo);
+
+    String buildFileContent =
+        String.format(
+            "%s\n%s",
+            loadRule(""), callRule("call_write_text", "out.txt", HELLO_FROM_EXTERNAL_REPOSITORY));
+    context()
+        .write(
+            "MODULE.bazel",
+            "new_git_repository = use_repo_rule(\"@bazel_tools//tools/build_defs/repo:git.bzl\","
+                + " \"new_git_repository\")",
+            "new_git_repository(",
+            "  name='ext',",
+            String.format("  remote='%s',", PathUtils.pathToFileURI(repo.resolve(".git"))),
+            String.format("  build_file_content=\"\"\"%s\"\"\",", buildFileContent),
+            ")");
+
+    // This creates Bazel without MSYS, see implementation for details.
+    BuilderRunner bazel = WorkspaceTestUtils.bazel(context());
+    bazel.build("@ext//:call_write_text");
+    Path outPath = context().resolveBinPath(bazel, "external/+new_git_repository+ext/out.txt");
+    WorkspaceTestUtils.assertLinesExactly(outPath, HELLO_FROM_EXTERNAL_REPOSITORY);
+  }
+
   /**
    * Tests usage of git_repository workspace rule in the particular use case, when only the commit
    * hash is specified, and the commit is not in the HEAD-reachable subtree, on a separate branch.

src/test/shell/bazel/starlark_git_repository_test.sh

@@ -181,6 +181,10 @@ function test_new_git_repository_with_build_file_strip_prefix() {
   do_new_git_repository_test "3-subdir-bare" "build_file" "pluto"
 }
 
+function test_new_git_repository_with_build_file_strip_prefix_default_branch() {
+  do_new_git_repository_test "" "build_file" "pluto"
+}
+
 function test_new_git_repository_with_build_file_content() {
   do_new_git_repository_test "0-initial" "build_file_content"
 }
@@ -189,6 +193,10 @@ function test_new_git_repository_with_build_file_content_strip_prefix() {
   do_new_git_repository_test "3-subdir-bare" "build_file_content" "pluto"
 }
 
+function test_new_git_repository_with_build_file_content_strip_prefix_default_branch() {
+  do_new_git_repository_test "" "build_file_content" "pluto"
+}
+
 # Test cloning a Git repository using the new_git_repository rule.
 #
 # This test uses the pluto Git repository at tag 0-initial, which contains the
@@ -203,6 +211,9 @@ function test_new_git_repository_with_build_file_content_strip_prefix() {
 #   pluto/
 #     info
 #
+# Finally, it uses the pluto Git repository at the default branch, which is the
+# master branch, which is at the same revision as the 3-subdir-bare tag.
+#
 # Set up workspace with the following files:
 #
 # $WORKSPACE_DIR/
@@ -217,17 +228,19 @@ function test_new_git_repository_with_build_file_content_strip_prefix() {
 function do_new_git_repository_test() {
   local pluto_repo_dir=$(get_pluto_repo)
   local strip_prefix=""
+  local tag=""
   [ $# -eq 3 ] && strip_prefix="strip_prefix=\"$3\","
+  [ "$1" != "" ] && tag="tag = \"$1\","
 
   # Create a workspace that clones the repository at the first commit.
 
-  if [ "$2" == "build_file" ] ; then
+  if [ "$2" == "build_file" ]; then
     cat >> MODULE.bazel <<EOF
 new_git_repository = use_repo_rule('@bazel_tools//tools/build_defs/repo:git.bzl', 'new_git_repository')
 new_git_repository(
     name = "pluto",
     remote = "$pluto_repo_dir",
-    tag = "$1",
+    $tag
     build_file = "//:pluto.BUILD",
     $strip_prefix
 )
@@ -249,7 +262,7 @@ new_git_repository = use_repo_rule('@bazel_tools//tools/build_defs/repo:git.bzl'
 new_git_repository(
     name = "pluto",
     remote = "$pluto_repo_dir",
-    tag = "$1",
+    $tag
     $strip_prefix
     build_file_content = """
 filegroup(
@@ -626,33 +639,7 @@ EOF
 
   bazel fetch //planets:planet-info >& $TEST_log \
     || echo "Expect run to fail."
-  expect_log "Exactly one of commit"
-}
-
-# Verifies that rule fails if neither tag or commit are set.
-#
-# This test uses the pluto Git repository at tag 1-build, which contains the
-# following files:
-#
-# pluto/
-#   MODULE.bazel
-#   BUILD
-#   info
-function test_git_repository_no_commit_tag_error() {
-  setup_error_test
-  local pluto_repo_dir=$(get_pluto_repo)
-
-  cat >> MODULE.bazel <<EOF
-git_repository = use_repo_rule('@bazel_tools//tools/build_defs/repo:git.bzl', 'git_repository')
-git_repository(
-    name = "pluto",
-    remote = "$pluto_repo_dir",
-)
-EOF
-
-  bazel fetch //planets:planet-info >& $TEST_log \
-    || echo "Expect run to fail."
-  expect_log "Exactly one of commit"
+  expect_log "At most one of commit"
 }
 
 # Verifies that if a non-existent subdirectory is supplied, then strip_prefix

tools/build_defs/repo/git.bzl

@@ -30,11 +30,10 @@ load(
 )
 
 def _clone_or_update_repo(ctx):
-    if ((not ctx.attr.tag and not ctx.attr.commit and not ctx.attr.branch) or
-        (ctx.attr.tag and ctx.attr.commit) or
+    if ((ctx.attr.tag and ctx.attr.commit) or
         (ctx.attr.tag and ctx.attr.branch) or
         (ctx.attr.commit and ctx.attr.branch)):
-        fail("Exactly one of commit, tag, or branch must be provided")
+        fail("At most one of commit, tag, or branch may be provided")
 
     root = ctx.path(".")
     directory = str(root)
@@ -225,11 +224,12 @@ git_repository = repository_rule(
     attrs = _common_attrs,
     doc = """Clone an external git repository.
 
-Clones a Git repository, checks out the specified tag, or commit, and
-makes its targets available for binding. Also determine the id of the
-commit actually checked out and its date, and return a dict with parameters
-that provide a reproducible version of this rule (which a tag not necessarily
-is).
+Clones a Git repository, checks out the specified branch, tag, or commit, and
+makes its targets available for binding. If no branch, tag or commit is
+specified, check out the repository's default branch. Also determine the id
+and date of the commit that was checked out, and return a dict with
+parameters that provide a reproducible version of this rule (which a tag or
+branch not necessarily is).
 
 Bazel will first try to perform a shallow fetch of only the specified commit.
 If that fails (usually due to missing server support), it will fall back to a

tools/build_defs/repo/git_worker.bzl

@@ -27,9 +27,9 @@ _GitRepoInfo = provider(
         "directory": "Working directory path",
         "shallow": "Defines the depth of a fetch. Either empty, --depth=1, or --shallow-since=<>",
         "reset_ref": """Reference to use for resetting the git repository.
-Either commit hash, tag or branch.""",
+Either commit hash, tag, branch name, or default branch.""",
         "fetch_ref": """Reference for fetching.
-Either commit hash, tag or branch.""",
+Either commit hash, tag, branch name, or default branch.""",
         "remote": "URL of the git repository to fetch from.",
         "init_submodules": """If True, submodules update command will be called after fetching
 and resetting to the specified reference.""",
@@ -75,6 +75,9 @@ def git_repo(ctx, directory):
     elif ctx.attr.branch:
         reset_ref = "origin/" + ctx.attr.branch
         fetch_ref = ctx.attr.branch + ":origin/" + ctx.attr.branch
+    else:
+        reset_ref = "origin/HEAD"
+        fetch_ref = "HEAD:refs/remotes/origin/HEAD"
 
     git_repo = _GitRepoInfo(
         directory = ctx.path(directory),