Document how to use --reference

Message ID 20200112190328.17906-1-andi@firstfloor.org
State New
Headers show
Series
  • Document how to use --reference
Related show

Commit Message

Andi Kleen Jan. 12, 2020, 7:03 p.m.
From: Andi Kleen <ak@linux.intel.com>


By popular demand, I did some updates to the git documentation how
to use --reference to save disk space.

Also recommend https instead of http (even though both are currently
broken)

---
 htdocs/git.html | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

-- 
2.24.0

Comments

Andreas Schwab Jan. 12, 2020, 7:51 p.m. | #1
On Jan 12 2020, Andi Kleen wrote:

> By popular demand, I did some updates to the git documentation how

> to use --reference to save disk space.


I would advice against using --reference.  Nowadays, git worktree is a
much safer option.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."
Gerald Pfeifer Jan. 12, 2020, 8:51 p.m. | #2
On Sun, 12 Jan 2020, Andi Kleen wrote:
> By popular demand, I did some updates to the git documentation how

> to use --reference to save disk space.

> 

> Also recommend https instead of http (even though both are currently

> broken)


Thank you, Andi.  Why https over http in this case?  Isn't git itself
cryptographically secured?  To avoid man in the middle injections via
an "alternate" repository presented?

Below is a minor update on top of yours that I applied.  Hope that's
fine.

Gerald

- Log -----------------------------------------------------------------
commit 8a488efcc0f4265505205aef285ae4a7537ff390
Author: Gerald Pfeifer <gerald@pfeifer.com>
Date:   Sun Jan 12 21:43:59 2020 +0100

    Refine the note on local clones, add markup, break a long line.

diff --git a/htdocs/git.html b/htdocs/git.html
index 41e2d953..7f40c0f6 100644
--- a/htdocs/git.html
+++ b/htdocs/git.html
@@ -45,17 +45,18 @@ check out the GCC sources using the following command:</p>
 <p>If you are behind a firewall that does not allow the git protocol
 through, you can replace <code>git://</code> with <code>https://</code>.
 
-<p>When doing multiple clones to different repositories you can avoid
v-redownloading the whole repository by using --reference.
-For example
+<p>When doing multiple clones to several local repositories you can avoid
+re-downloading everything by using <code>--reference</code>, e.g.
+
 <blockquote><code>git clone --reference original-gcc ssh://gcc.gnu.org/git.gcc.git new-gcc</code></blockquote>
-This will also save some disk space. Git will do this automatically when cloning from a local repository on the same file system. It is also possible to do a
-shallow checkout with --depth to limit history, but that might limit your
-ability to work with existing branches.
 
-You should only use the https protocol if
-the git protocol does not work; the https protocol has a higher server
-overhead associated with it and will be slower.</p>
+This will also save disk space. Git will do this automatically when cloning
+from a local repository on the same file system. It is also possible to do a
+shallow checkout with <code>--depth</code> to limit history, but that might
+limit your ability to work with existing branches.
+
+(Only use the https protocol if the git protocol does not work; https has
+a higher server overhead and will be slower.)</p>
 
 <!-- Comment out till savannah gets back to us (see above)
 <p>In case of problems with the repository at savannah.gnu.org please
Andi Kleen Jan. 13, 2020, 1:09 a.m. | #3
On Sun, Jan 12, 2020 at 09:51:22PM +0100, Gerald Pfeifer wrote:
> On Sun, 12 Jan 2020, Andi Kleen wrote:

> > By popular demand, I did some updates to the git documentation how

> > to use --reference to save disk space.

> > 

> > Also recommend https instead of http (even though both are currently

> > broken)

> 

> Thank you, Andi.  Why https over http in this case?  Isn't git itself

> cryptographically secured?  To avoid man in the middle injections via

> an "alternate" repository presented?


git is secure once you have the hashes, but I don't think the protocol
itself is secure. So a MITM could give you some bogus hashes.

> 

> Below is a minor update on top of yours that I applied.  Hope that's

> fine.


Thanks.

-Andi
Andi Kleen Jan. 13, 2020, 1:10 a.m. | #4
On Sun, Jan 12, 2020 at 08:51:28PM +0100, Andreas Schwab wrote:
> On Jan 12 2020, Andi Kleen wrote:

> 

> > By popular demand, I did some updates to the git documentation how

> > to use --reference to save disk space.

> 

> I would advice against using --reference.  Nowadays, git worktree is a

> much safer option.


Feel free to do further edits. The file probably needs further work
anyways.

-Andi

Patch

diff --git a/htdocs/git.html b/htdocs/git.html
index 0166ff74..41e2d953 100644
--- a/htdocs/git.html
+++ b/htdocs/git.html
@@ -43,9 +43,18 @@  check out the GCC sources using the following command:</p>
 </p></blockquote>
 
 <p>If you are behind a firewall that does not allow the git protocol
-through, you can replace <code>git://</code> with <code>http://</code>.
-You should only use the http protocol if
-the git protocol does not work; the http protocol has a higher server
+through, you can replace <code>git://</code> with <code>https://</code>.
+
+<p>When doing multiple clones to different repositories you can avoid
+redownloading the whole repository by using --reference.
+For example
+<blockquote><code>git clone --reference original-gcc ssh://gcc.gnu.org/git.gcc.git new-gcc</code></blockquote>
+This will also save some disk space. Git will do this automatically when cloning from a local repository on the same file system. It is also possible to do a
+shallow checkout with --depth to limit history, but that might limit your
+ability to work with existing branches.
+
+You should only use the https protocol if
+the git protocol does not work; the https protocol has a higher server
 overhead associated with it and will be slower.</p>
 
 <!-- Comment out till savannah gets back to us (see above)