[Savannah-cvs] [431] Improve UsingGit documentation

[bob]

Revision: 431
          
http://svn.savannah.gnu.org/viewvc/?view=rev&root=administration&revision=431
Author:   rwp
Date:     2021-01-26 23:05:31 -0500 (Tue, 26 Jan 2021)
Log Message:
-----------
Improve UsingGit documentation

Emphasize that "/r/" is the difference from "/git/" and /r/ is the
dumb protocol whereas /git/ is the normal smart protocol.

Try to make the use of https, http, git protocols more internally
consistent and the reasons for using specific ones more clear.

Modified Paths:
--------------
    trunk/sviki/UsingGit.mdwn

Modified: trunk/sviki/UsingGit.mdwn
===================================================================
--- trunk/sviki/UsingGit.mdwn   2021-01-10 09:55:30 UTC (rev 430)
+++ trunk/sviki/UsingGit.mdwn   2021-01-27 04:05:31 UTC (rev 431)
@@ -19,8 +19,20 @@
   switched to the git smart http protocol the same as the above
   `/git/` path, making this URL redundant with the above)
 
+The **links in bold** are the preferred and recommended protocols to
+use.  This because they are encrypted to protect against possible
+man-in-the-middle data corruption.  This also protects against broken
+site proxies and other misconfiguration.  And also snooping too!  The
+other link types are also available for those that can't make use of
+the encryption protected protocols.
+
+Both `sv.gnu.org` and `savannah.gnu.org` and the same for nongnu.org
+are all the same.  Use whichever you prefer using.  Also all of the
+domain names exist in both `gnu.org` and `nongnu.org` domains.
+
 Web browser:
 <http://git.savannah.gnu.org/gitweb/>
+<http://git.savannah.gnu.org/cgit/>
 
 If you use ssh-based access, please verify the host keys first at
 [[SshAccess]]
@@ -35,32 +47,41 @@
 
 -   Checkout (read-only):
 
-        git clone git://git.sv.gnu.org/project.git
+        git clone https://git.savannah.gnu.org/project.git
 
+    or
+
+        git clone git://git.savannah.gnu.org/project.git
+
     For example cloning the GNU Hello project.
 
-        git clone http://git.savannah.gnu.org/git/hello
+        git clone https://git.savannah.gnu.org/git/hello
 
+    or
+
+        git clone git://git.savannah.gnu.org/hello
+
 -   Firewall checkout (read-only): if you're behind a
     outgoing-traffic-filtering firewall, you can use Git's "dumb
-    protocol" via HTTP - note that this is SLOWER, both for you and
-    Savannah. Avoid if possible, and please tell your local sysadmin
-    to allow outgoing git traffic (port 9418):
+    protocol" via HTTP.  The difference here is the `/r/` part of the
+    path instead of the `/git/` path for the https and http protocols.
+    Note that the git dumb protocols is SLOWER, both for you and
+    Savannah. But this may work when both `git://` and `https://` are
+    blocked. Avoid if possible, and please tell your local sysadmin
+    to allow https and/or git protocol on port 9418:
 
         git clone http://git.savannah.gnu.org/r/project.git
 
-    Note: we enabled `git-http-backend` (a CGI script) to speed up HTTP
-    cloning, but this is still not the recommended protocol.
+-   Project member checkout: If you want to be able to push your changes
+    back into the repository on Savannah then members must use ssh
+    protocol to have write access.
 
--   Project member checkout: if you want to be able to push your changes
-    back into the repository on savannah:
+        git clone ssh://login@git.sv.gnu.org/srv/git/project.git
 
+    Or using the alternative scp-like format.  Both are equivalent.
+
         git clone login@git.sv.gnu.org:/srv/git/project.git
 
-    Or using the URL format:
-
-        git clone ssh://login@git.sv.gnu.org/srv/git/project.git
-
 Note that the ssh transport requires an active Savannah account and
 you must be a member of at least one project group in order for your
 account to be enabled.