From b462128f3d39d065e0871b98d076ab9fb186e724 Mon Sep 17 00:00:00 2001
From: kchodorow <kchodorow@google.com>
Date: Tue, 18 Apr 2017 21:21:51 +0200
Subject: [PATCH] Add warning to git_repository

#2147

PiperOrigin-RevId: 153494286
---
 .../rules/workspace/GitRepositoryRule.java    | 35 ++++++++++++++++++
 .../rules/workspace/NewGitRepositoryRule.java | 36 +++++++++++++++++++
 2 files changed, 71 insertions(+)

diff --git a/src/main/java/com/google/devtools/build/lib/bazel/rules/workspace/GitRepositoryRule.java b/src/main/java/com/google/devtools/build/lib/bazel/rules/workspace/GitRepositoryRule.java
index f1cc2bc58b1458..37aa7b9e4d8de6 100644
--- a/src/main/java/com/google/devtools/build/lib/bazel/rules/workspace/GitRepositoryRule.java
+++ b/src/main/java/com/google/devtools/build/lib/bazel/rules/workspace/GitRepositoryRule.java
@@ -74,6 +74,41 @@ public Metadata getMetadata() {
 
 /*<!-- #BLAZE_RULE (NAME = git_repository, TYPE = OTHER, FAMILY = Workspace)[GENERIC_RULE] -->
 
+<em><p>Warning: this rule has several limitations. We recommend using
+<a href="#http_archive"><code>http_archive</code></a> instead for more robust and secure
+performance.</p>
+
+<p><code>git_repository</code> has several issues:
+
+<ul>
+<li>Security - <code>http_archive</code> allows a sha256 to be specified, which ensures that the
+downloaded code is exactly what was expected.
+<li>Reliability - <code>http_archive</code> allows the user to specify multiple URLs to attempt
+downloads from. Most services have downtime occasionally, so specifying multiple remotes decreases
+the chances of being unable to download a dependency.
+<li>Speed - <code>http_archive</code> multiplexes downloads to get the fastest possible rate.
+You can also generally download a tarball that is a "shallow clone" of the repository, which
+decreases the size of the download.
+<li>Library issues - This implementation uses jGit, which we've discovered
+<a href="https://github.com/bazelbuild/bazel/issues/2802">several issues</a> with. It also lacks
+support for some authentication types you might use with your system git.
+</ul>
+
+<p>Many git repository hosts serve tarballs of the repository, so depend on those if possible.
+For GitHub, this takes the form:
+
+<pre>
+http_archive(
+    name = "<name>",
+    urls = ["https://github.com/<user>/<repo>/archive/<commit or tag>.tar.gz"],
+)
+</pre>
+
+If you are using a private repository, prefer the
+<a href="https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/repo/git.bzl">Skylark git
+repository rules</a>, which will use your system's git install (instead of jGit). These rules
+are built into Bazel and have the same API as the native rules.</p></em>
+
 <p>Clones a Git repository, checks out the specified tag, or commit, and makes its targets
 available for binding.</p>
 
diff --git a/src/main/java/com/google/devtools/build/lib/bazel/rules/workspace/NewGitRepositoryRule.java b/src/main/java/com/google/devtools/build/lib/bazel/rules/workspace/NewGitRepositoryRule.java
index 4cda4d71caad62..8659f5d5a90cd9 100644
--- a/src/main/java/com/google/devtools/build/lib/bazel/rules/workspace/NewGitRepositoryRule.java
+++ b/src/main/java/com/google/devtools/build/lib/bazel/rules/workspace/NewGitRepositoryRule.java
@@ -106,6 +106,42 @@ public Metadata getMetadata() {
 
 /*<!-- #BLAZE_RULE (NAME = new_git_repository, TYPE = OTHER, FAMILY = Workspace)[GENERIC_RULE] -->
 
+<em><p>Warning: this rule has several limitations. We recommend using
+<a href="#new_http_archive"><code>new_http_archive</code></a> instead for more robust and
+secure performance.</p>
+
+<p><code>new_git_repository</code> has several issues:
+
+<ul>
+<li>Security - <code>new_http_archive</code> allows a sha256 to be specified, which ensures that
+the downloaded code is exactly what was expected.
+<li>Reliability - <code>new_http_archive</code> allows the user to specify multiple URLs to attempt
+downloads from. Most services have downtime occasionally, so specifying multiple remotes decreases
+the chances of being unable to download a dependency.
+<li>Speed - <code>new_http_archive</code> multiplexes downloads to get the fastest possible rate.
+You can also generally download a tarball that is a "shallow clone" of the repository, which
+decreases the size of the download.
+<li>Library issues - This implementation uses jGit, which we've discovered
+<a href="https://github.com/bazelbuild/bazel/issues/2802">several issues</a> with. It also lacks
+support for some authentication types you might use with your system git.
+</ul>
+
+<p>Many git repository hosts serve tarballs of the repository, so depend on those if possible.
+For GitHub, this takes the form:
+
+<pre>
+new_http_archive(
+    name = "<name>",
+    urls = ["https://github.com/<user>/<repo>/archive/<commit or tag>.tar.gz"],
+    build_file = "<build file>",
+)
+</pre>
+
+If you are using a private repository, prefer the
+<a href="https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/repo/git.bzl">Skylark git
+repository rules</a>, which will use your system's git install (instead of jGit). These rules
+are built into Bazel and have the same API as the native rules.</p></em>
+
 <p>Clones a Git repository, checks out the specified tag, or commit, and makes its targets
 available for binding.</p>