[PATCH] doc: clarification for hashing git checkouts

[PATCH] doc: clarification for hashing git checkouts

[Troy Sankey]

When hashing git checkouts of packages, packagers must first remove the .git
directory.  This commit adds this clarification to the "Invoking guix hash"
page in the documentation.
---
 doc/guix.texi | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/doc/guix.texi b/doc/guix.texi
index c9d9bd8..f9fe85a 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -4533,6 +4533,9 @@ hash (@pxref{Invoking guix archive}).
 @c FIXME: Replace xref above with xref to an ``Archive'' section when
 @c it exists.
 
+When hashing a git checkout, be sure to remove the git configuration
+directory (@code{rm -r .git}) as it will erroneously impact the hash.
+
 @end table
 
 @node Invoking guix import
-- 
2.1.4

Re: [PATCH] doc: clarification for hashing git checkouts

[Leo Famulari]

On Sun, Jul 10, 2016 at 05:54:38PM -0400, Troy Sankey wrote:
> When hashing git checkouts of packages, packagers must first remove the .git
> directory.  This commit adds this clarification to the "Invoking guix hash"
> page in the documentation.

Yes! This is one that *everybody* has to ask.

I think it would be better in section '5.1.2 origin reference', because
that is where the origin methods (url-fetch, git-fetch, etc) and the
sha256 field are documented.

In that case, it could go along with explanations of how to calculate
the hash for cvs-download, hg-download, and svn-download.

What do others think?

Re: [PATCH] doc: clarification for hashing git checkouts

[Pjotr Prins]

On Sun, Jul 10, 2016 at 07:16:30PM -0400, Leo Famulari wrote:
> On Sun, Jul 10, 2016 at 05:54:38PM -0400, Troy Sankey wrote:
> > When hashing git checkouts of packages, packagers must first remove the .git
> > directory.  This commit adds this clarification to the "Invoking guix hash"
> > page in the documentation.
> 
> Yes! This is one that *everybody* has to ask.

And only now I am understanding a problem ages ago. Would this also be
the reason for git sub-modules not to work? We don't use them, but
sometimes it would be a nice intermediate stage for writing a package
definition.

Pj.

Re: [PATCH] doc: clarification for hashing git checkouts

[Troy Sankey]

[-- Attachment #1: Type: text/plain, Size: 1195 bytes --]

Quoting Leo Famulari (2016-07-10 19:16:30)
> On Sun, Jul 10, 2016 at 05:54:38PM -0400, Troy Sankey wrote:
> > When hashing git checkouts of packages, packagers must first remove the .git
> > directory.  This commit adds this clarification to the "Invoking guix hash"
> > page in the documentation.
> 
> Yes! This is one that *everybody* has to ask.

I've asked it, and I've since seen two more ask on IRC :)

> I think it would be better in section '5.1.2 origin reference', because
> that is where the origin methods (url-fetch, git-fetch, etc) and the
> sha256 field are documented.
> 
> In that case, it could go along with explanations of how to calculate
> the hash for cvs-download, hg-download, and svn-download.
> 
> What do others think?

I think what is really missing is a reference to 'Invoking guix hash' from
'5.1.2 origin reference'.  My new patch includes that reference, along with
your other suggested explainations about other VCS.  I think it is important
that we direct people to the right tools for the job---beginning packagers
should not yet be concerned about the specifics of using 'guix hash' before
they learn the name of the tool.

Troy


[-- Attachment #2: 0001-doc-clarification-for-hashing-git-checkouts.patch --]
[-- Type: text/x-diff, Size: 2216 bytes --]

From 42b26d3601a6318bcefa4dfe4018daddc521e27a Mon Sep 17 00:00:00 2001
From: Troy Sankey <sankeytms@gmail.com>
Date: Sun, 10 Jul 2016 17:45:55 -0400
Subject: [PATCH] doc: clarification for hashing git checkouts

When hashing git checkouts of packages, packagers must first remove the .git
directory.  This commit adds this clarification to the "Invoking guix hash"
section in the documentation, and makes a few more related changes throughout
the rest of the document.
---
 doc/guix.texi | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index c9d9bd8..26284ac 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -2425,7 +2425,7 @@ The @code{sha256} field specifies the expected SHA256 hash of the file
 being downloaded.  It is mandatory, and allows Guix to check the
 integrity of the file.  The @code{(base32 @dots{})} form introduces the
 base32 representation of the hash.  You can obtain this information with
-@code{guix download} (@pxref{Invoking guix download}) and @code{guix
+@code{guix download} (@pxref{Invoking guix download}) or @code{guix
 hash} (@pxref{Invoking guix hash}).
 
 @cindex patches
@@ -2684,7 +2684,9 @@ specified in the @code{uri} field as a @code{git-reference} object; a
 @item @code{sha256}
 A bytevector containing the SHA-256 hash of the source.  Typically the
 @code{base32} form is used here to generate the bytevector from a
-base-32 string.
+base-32 string.  You can obtain this information with @code{guix
+download} (@pxref{Invoking guix download}) or @code{guix hash}
+(@pxref{Invoking guix hash}).
 
 @item @code{file-name} (default: @code{#f})
 The file name under which the source code should be saved.  When this is
@@ -4533,6 +4535,11 @@ hash (@pxref{Invoking guix archive}).
 @c FIXME: Replace xref above with xref to an ``Archive'' section when
 @c it exists.
 
+When hashing a git checkout, be sure to remove the git configuration
+directory (@code{rm -r .git}) as it will erroneously impact the hash.
+The same is true for other version control checkouts (@code{rm -r .hg},
+@code{rm -r .svn}, etc.)
+
 @end table
 
 @node Invoking guix import
-- 
2.1.4

Re: [PATCH] doc: clarification for hashing git checkouts

[Troy Sankey]

Quoting Pjotr Prins (2016-07-10 20:13:26)
> And only now I am understanding a problem ages ago. Would this also be
> the reason for git sub-modules not to work?

Pjotr,

If I'm understanding correctly, you failed to generate the hash of a git
repository containing submodules?  In that case, you may need to delete the
.git file under each submodule directory in addition to the top level .git
directory.

Hashing sources is becoming quite compilated!  I can't wait until 'guix
download' supports git, then this could be automated.

Troy

Re: [PATCH] doc: clarification for hashing git checkouts

[Pjotr Prins]

Yes, that is how I understand it previously did not work for me.
Thanks :)

On Mon, Jul 11, 2016 at 01:33:40AM -0400, Troy Sankey wrote:
> Quoting Pjotr Prins (2016-07-10 20:13:26)
> > And only now I am understanding a problem ages ago. Would this also be
> > the reason for git sub-modules not to work?
> 
> Pjotr,
> 
> If I'm understanding correctly, you failed to generate the hash of a git
> repository containing submodules?  In that case, you may need to delete the
> .git file under each submodule directory in addition to the top level .git
> directory.
> 
> Hashing sources is becoming quite compilated!  I can't wait until 'guix
> download' supports git, then this could be automated.
> 
> Troy
> 

-- 

Re: [PATCH] doc: clarification for hashing git checkouts

[Leo Famulari]

On Mon, Jul 11, 2016 at 01:33:40AM -0400, Troy Sankey wrote:
> Hashing sources is becoming quite compilated!  I can't wait until 'guix
> download' supports git, then this could be automated.

In that case, `guix download` would need to take a Git hash as an
argument.

In general, I think it's a good idea to avoid `guix download` when
writing packages, unless you make sure to double-check that the
package's origin field works as expected. I've submitted packages with a
bad URL that was masked because the tarball was already in my store from
`guix download`. So, now I always download my sources "by hand" and
calculate the hash from the result of that.

Re: [PATCH] doc: clarification for hashing git checkouts

[ng0]

Hi,

Troy Sankey writes:

> Quoting Leo Famulari (2016-07-10 19:16:30)
>> On Sun, Jul 10, 2016 at 05:54:38PM -0400, Troy Sankey wrote:
>> > When hashing git checkouts of packages, packagers must first remove the .git
>> > directory.  This commit adds this clarification to the "Invoking guix hash"
>> > page in the documentation.
>> 
>> Yes! This is one that *everybody* has to ask.
>
> I've asked it, and I've since seen two more ask on IRC :)
>
>> I think it would be better in section '5.1.2 origin reference', because
>> that is where the origin methods (url-fetch, git-fetch, etc) and the
>> sha256 field are documented.
>> 
>> In that case, it could go along with explanations of how to calculate
>> the hash for cvs-download, hg-download, and svn-download.
>> 
>> What do others think?
>
> I think what is really missing is a reference to 'Invoking guix hash' from
> '5.1.2 origin reference'.  My new patch includes that reference, along with
> your other suggested explainations about other VCS.  I think it is important
> that we direct people to the right tools for the job---beginning packagers
> should not yet be concerned about the specifics of using 'guix hash' before
> they learn the name of the tool.
>
> Troy
>

Thanks for the contribution.

The patch below reads okay to me, could you add your name or
nickname in the section of guix.texi where document author names
are included, if applicable (ie if your name is missing before
this edit)?

> From 42b26d3601a6318bcefa4dfe4018daddc521e27a Mon Sep 17 00:00:00 2001
> From: Troy Sankey <sankeytms@gmail.com>
> Date: Sun, 10 Jul 2016 17:45:55 -0400
> Subject: [PATCH] doc: clarification for hashing git checkouts
>
> When hashing git checkouts of packages, packagers must first remove the .git
> directory.  This commit adds this clarification to the "Invoking guix hash"
> section in the documentation, and makes a few more related changes throughout
> the rest of the document.
> ---
>  doc/guix.texi | 11 +++++++++--
>  1 file changed, 9 insertions(+), 2 deletions(-)
>
> diff --git a/doc/guix.texi b/doc/guix.texi
> index c9d9bd8..26284ac 100644
> --- a/doc/guix.texi
> +++ b/doc/guix.texi
> @@ -2425,7 +2425,7 @@ The @code{sha256} field specifies the expected SHA256 hash of the file
>  being downloaded.  It is mandatory, and allows Guix to check the
>  integrity of the file.  The @code{(base32 @dots{})} form introduces the
>  base32 representation of the hash.  You can obtain this information with
> -@code{guix download} (@pxref{Invoking guix download}) and @code{guix
> +@code{guix download} (@pxref{Invoking guix download}) or @code{guix
>  hash} (@pxref{Invoking guix hash}).
>  
>  @cindex patches
> @@ -2684,7 +2684,9 @@ specified in the @code{uri} field as a @code{git-reference} object; a
>  @item @code{sha256}
>  A bytevector containing the SHA-256 hash of the source.  Typically the
>  @code{base32} form is used here to generate the bytevector from a
> -base-32 string.
> +base-32 string.  You can obtain this information with @code{guix
> +download} (@pxref{Invoking guix download}) or @code{guix hash}
> +(@pxref{Invoking guix hash}).
>  
>  @item @code{file-name} (default: @code{#f})
>  The file name under which the source code should be saved.  When this is
> @@ -4533,6 +4535,11 @@ hash (@pxref{Invoking guix archive}).
>  @c FIXME: Replace xref above with xref to an ``Archive'' section when
>  @c it exists.
>  
> +When hashing a git checkout, be sure to remove the git configuration
> +directory (@code{rm -r .git}) as it will erroneously impact the hash.
> +The same is true for other version control checkouts (@code{rm -r .hg},
> +@code{rm -r .svn}, etc.)
> +
>  @end table
>  
>  @node Invoking guix import

-- 
♥Ⓐ  ng0
For non-prism friendly talk find me on http://www.psyced.org
SecuShare – http://secushare.org

Re: [PATCH] doc: clarification for hashing git checkouts

[Troy Sankey]

[-- Attachment #1: Type: text/plain, Size: 292 bytes --]

Quoting ng0 (2016-07-11 12:35:49)
> The patch below reads okay to me, could you add your name or
> nickname in the section of guix.texi where document author names
> are included, if applicable (ie if your name is missing before
> this edit)?

Attached patch includes my name.

Troy

[-- Attachment #2: 0001-doc-clarification-for-hashing-git-checkouts.patch --]
[-- Type: text/x-diff, Size: 2727 bytes --]

From 6381b62a3774001f630d868fa7e58acc28b0cc4f Mon Sep 17 00:00:00 2001
From: Troy Sankey <sankeytms@gmail.com>
Date: Sun, 10 Jul 2016 17:45:55 -0400
Subject: [PATCH] doc: clarification for hashing git checkouts

When hashing git checkouts of packages, packagers must first remove the .git
directory.  This commit adds this clarification to the "Invoking guix hash"
section in the documentation, and makes a few more related changes throughout
the rest of the document.
---
 doc/guix.texi | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index c9d9bd8..d809694 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -19,7 +19,8 @@ Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer@*
 Copyright @copyright{} 2015, 2016 Leo Famulari@*
 Copyright @copyright{} 2016 Ben Woodcroft@*
 Copyright @copyright{} 2016 Chris Marusich@*
-Copyright @copyright{} 2016 Efraim Flashner
+Copyright @copyright{} 2016 Efraim Flashner@*
+Copyright @copyright{} 2016 Troy Sankey
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -2425,7 +2426,7 @@ The @code{sha256} field specifies the expected SHA256 hash of the file
 being downloaded.  It is mandatory, and allows Guix to check the
 integrity of the file.  The @code{(base32 @dots{})} form introduces the
 base32 representation of the hash.  You can obtain this information with
-@code{guix download} (@pxref{Invoking guix download}) and @code{guix
+@code{guix download} (@pxref{Invoking guix download}) or @code{guix
 hash} (@pxref{Invoking guix hash}).
 
 @cindex patches
@@ -2684,7 +2685,9 @@ specified in the @code{uri} field as a @code{git-reference} object; a
 @item @code{sha256}
 A bytevector containing the SHA-256 hash of the source.  Typically the
 @code{base32} form is used here to generate the bytevector from a
-base-32 string.
+base-32 string.  You can obtain this information with @code{guix
+download} (@pxref{Invoking guix download}) or @code{guix hash}
+(@pxref{Invoking guix hash}).
 
 @item @code{file-name} (default: @code{#f})
 The file name under which the source code should be saved.  When this is
@@ -4533,6 +4536,11 @@ hash (@pxref{Invoking guix archive}).
 @c FIXME: Replace xref above with xref to an ``Archive'' section when
 @c it exists.
 
+When hashing a git checkout, be sure to remove the git configuration
+directory (@code{rm -r .git}) as it will erroneously impact the hash.
+The same is true for other version control checkouts (@code{rm -r .hg},
+@code{rm -r .svn}, etc.)
+
 @end table
 
 @node Invoking guix import
-- 
2.1.4

Re: [PATCH] doc: clarification for hashing git checkouts

[Ludovic Courtès]

Troy Sankey <sankeytms@gmail.com> skribis:

> Quoting ng0 (2016-07-11 12:35:49)
>> The patch below reads okay to me, could you add your name or
>> nickname in the section of guix.texi where document author names
>> are included, if applicable (ie if your name is missing before
>> this edit)?
>
> Attached patch includes my name.
>
> Troy
>
> From 6381b62a3774001f630d868fa7e58acc28b0cc4f Mon Sep 17 00:00:00 2001
> From: Troy Sankey <sankeytms@gmail.com>
> Date: Sun, 10 Jul 2016 17:45:55 -0400
> Subject: [PATCH] doc: clarification for hashing git checkouts
>
> When hashing git checkouts of packages, packagers must first remove the .git
> directory.  This commit adds this clarification to the "Invoking guix hash"
> section in the documentation, and makes a few more related changes throughout
> the rest of the document.

I’ve pushed a variant of this as commit
db97a03a892c662f316c9fd6a497b4b2a18626b3.  Let me know if you think
something is amiss!

Thanks,
Ludo’.