[ANN] Pro Git Reedited 2nd Edition

[ANN] Pro Git Reedited 2nd Edition

[Jon Forrest]

This an announcement of Pro Git Reedited 2nd Edition, which is
a substantial edit of Chacon and Straub's Pro Git 2nd Edition.
I spent a lot of time tightening it up and maybe clearing
up some explanations.

The pdf is downloadable at:
https://drive.google.com/open?id=0B-Llso12P94-Ujg5Z1dhWUhhMm8

The complete self-contained HTML is at:
https://drive.google.com/file/d/0B-Llso12P94-U3g1aDBRWjk1Sk0

The sources for this book are at:
https://github.com/nobozo/progit2

I welcome comments.

Jon Forrest

Re: [ANN] Pro Git Reedited 2nd Edition

[Jakub Narębski]

W dniu 2016-07-24 o 06:07, Jon Forrest pisze:

> This an announcement of Pro Git Reedited 2nd Edition, which is
> a substantial edit of Chacon and Straub's Pro Git 2nd Edition.
> I spent a lot of time tightening it up and maybe clearing
> up some explanations.
[...]

> The sources for this book are at:
> https://github.com/nobozo/progit2

I have not checked the book itself; it would be nice if it were
hosted somewhere, even if using GitHub Pages (per-project or
per-user).

Could you change the description of the repository, and perhaps
adjust the README so that it says that it is Pro Git Reedited?
Have you tried submitting changes upstream?

Best,
-- 
Jakub Narębski
author of "Mastering Git"

Re: [ANN] Pro Git Reedited 2nd Edition

[Jakub Narębski]

Re-added git mailing list

On 24 July 2016 at 17:57, Jon Forrest <jonf@captricity.com> wrote:
> On 7/24/2016 2:00 AM, Jakub Narębski wrote:
>
>> I have not checked the book itself; it would be nice if it were
>> hosted somewhere, even if using GitHub Pages (per-project or
>> per-user).
>
> Do you mean in some format other than pdf and html?
> What's wrong with sharing on Google drive?

As far as I can see you cannot view it online (without downloading).

>> Could you change the description of the repository, and perhaps
>> adjust the README so that it says that it is Pro Git Reedited?
>
> Good idea. I'll do that.

Good.

>> Have you tried submitting changes upstream?
>
>
> Yes, but they're not interested because most of my
> changes are very subjective. I have submitted a couple
> of obvious minor errors, which do appear in the upstream
> version.

Ah. Could you tell me the summary of those changes?

-- 
Jakub Narebski

Re: [ANN] Pro Git Reedited 2nd Edition

[Jon Forrest]

On 7/24/2016 10:19 AM, Jakub Narębski wrote:

> As far as I can see you cannot view it online (without downloading).

True. I changed the way the HTML file is generated so that it
contains all the images downloading it is as good as viewing
it online. I'm not current with the thinking about the merits
of online viewing vs. downloading. Is one more accepted than the other?

Also, I realized one potentially major disadvantage of sharing in
Google Drive. This is that the URL will change each time I update
the book. Apparently Google is taking away the ability to create
a static link at the end of August 2016.

If this book turns out to be popular enough that I have to change it
then I'll have to revisit how to share it. Github Pages looks interesting
but it isn't clear to me how to put this book there since it's written
in Ascidoc.

> Ah. Could you tell me the summary of those changes?

There are too many to summarize. Some are of the type that the proofreader
should have caught, and others are my attempt to clarify things. Since I
don't claim to be a Git expert it remains to be seen how successful I am.

Jon

Re: [ANN] Pro Git Reedited 2nd Edition

[Jakub Narębski]

W dniu 2016-07-24 o 19:34, Jon Forrest pisze:
> On 7/24/2016 10:19 AM, Jakub Narębski wrote:
> 
>> As far as I can see you cannot view it online (without downloading).
> 
> True. I changed the way the HTML file is generated so that it
> contains all the images downloading it is as good as viewing
> it online. I'm not current with the thinking about the merits
> of online viewing vs. downloading. Is one more accepted than the other?

In my opinion being able to view it online has its advantages.
Even casual reader can check it, and point errors or offer suggestions
for improvements.

> Also, I realized one potentially major disadvantage of sharing in
> Google Drive. This is that the URL will change each time I update
> the book. Apparently Google is taking away the ability to create
> a static link at the end of August 2016.

I think you can share a folder instead, and this would be stable.
Alternatively, when updating the book you could update the link
in the GitHub repository description and/or the README for the
fork.

> If this book turns out to be popular enough that I have to change it
> then I'll have to revisit how to share it. Github Pages looks interesting
> but it isn't clear to me how to put this book there since it's written
> in AsciiDoc.

Well, https://git.github.io/htmldocs/git.html is on GitHub Pages
(for a project, that is in https://github.com/git/git.github.io repo
that is also used for Git Rev News), and it obviously uses AsciiDoc.

You can use Jekyll, or you can just upload HTML, as described
in https://help.github.com/articles/creating-project-pages-manually/
(this one is for per-repo GitHub Pages, i.e. using orphan branch
gh-pages, not a special named repository like e.g. git.github.io).
After each change / release you would need to rebuild HTML version
and upload to GitHub pages. This can be automated with hooks.

BTW. I thought that Pro Git used Markdown, not AsciiDoc?
 
>> Ah. Could you tell me the summary of those changes?
> 
> There are too many to summarize. Some are of the type that the proofreader
> should have caught, and others are my attempt to clarify things. Since I
> don't claim to be a Git expert it remains to be seen how successful I am.

All right. One issue I have after browsing through changes is that
description of changes and their granularity is severely lacking.
"A few more very minor changes.", "More piddly changes.", "should have
included this in last commit" are not good commit messages.

If I find time to comment on changes, I would do that on GitHub,
commenting / adding notes on changes there (like the one I posted
as demo: 
  https://github.com/nobozo/progit2/commit/43ae203c2ccf1a017153de1b41a8c47eb166dba1#commitcomment-18372006

Best,
-- 
Jakub Narebski

author of "Mastering Git"
https://www.packtpub.com/application-development/mastering-git
http://shop.oreilly.com/product/9781783553754.do
https://www.amazon.com/Mastering-Git-Jakub-Narebski/dp/1783553758
 

Re: [ANN] Pro Git Reedited 2nd Edition

[Jon Forrest]

On 7/24/2016 11:27 AM, Jakub Narębski wrote:

> In my opinion being able to view it online has its advantages.
> Even casual reader can check it, and point errors or offer suggestions
> for improvements.

Absolutely. Now that I've finished the editing I'll look
into that.

> I think you can share a folder instead, and this would be stable.
> Alternatively, when updating the book you could update the link
> in the GitHub repository description and/or the README for the
> fork.

I'll check your folder idea. If that's correct then that would
be an excellent way to do it. I had already thought of updating
the README but I'm not sure if this would be sufficient.

> Well, https://git.github.io/htmldocs/git.html is on GitHub Pages
> (for a project, that is in https://github.com/git/git.github.io repo
> that is also used for Git Rev News), and it obviously uses AsciiDoc.

I'll check that.

> You can use Jekyll, or you can just upload HTML, as described
> in https://help.github.com/articles/creating-project-pages-manually/
> (this one is for per-repo GitHub Pages, i.e. using orphan branch
> gh-pages, not a special named repository like e.g. git.github.io).
> After each change / release you would need to rebuild HTML version
> and upload to GitHub pages. This can be automated with hooks.

I'll also look into that.

These are all great suggestions, which I appreciate. I didn't
do any of this for the 1st edition, which, in retrospect,
was probably a mistake.

> BTW. I thought that Pro Git used Markdown, not AsciiDoc?

Nope. Asciidoc. See
https://medium.com/@chacon/living-the-future-of-technical-writing-2f368bd0a272#.fdhsp0zgj

> All right. One issue I have after browsing through changes is that
> description of changes and their granularity is severely lacking.
> "A few more very minor changes.", "More piddly changes.", "should have
> included this in last commit" are not good commit messages.

You're absolutely right. I probably should have squashed those commits.
Those comments aren't really intended for public consumption.
Since I made many changes per commit, I really couldn't give an
instructive commit message.

Now that this edition is done, I plan on following good commit
practices in the future.

> If I find time to comment on changes, I would do that on GitHub,
> commenting / adding notes on changes there (like the one I posted
> as demo:
>   https://github.com/nobozo/progit2/commit/43ae203c2ccf1a017153de1b41a8c47eb166dba1#commitcomment-18372006

That would be great. I think I'm setup for that now in my GitHub
repo for that book.

Jon

Re: [ANN] Pro Git Reedited 2nd Edition

[Jon Forrest]

>> Also, I realized one potentially major disadvantage of sharing in
>> Google Drive. This is that the URL will change each time I update
>> the book. Apparently Google is taking away the ability to create
>> a static link at the end of August 2016.
>
> I think you can share a folder instead, and this would be stable.
> Alternatively, when updating the book you could update the link
> in the GitHub repository description and/or the README for the
> fork.

By the way, I might have just figured out a good way of handling
static links with Google Drive.

Apparently, when I created the pdf version of Pro Git Reedited
2nd Edition (which I did on a Dropbox folder) I didn't wait
long enough for the creation process to complete (I think
that was the problem but I'm not 100% sure). Anyway, as
a result, the pdf version didn't have any images in it.

After fooling around for a while, I was able to create a
pdf that did contain the images but I was worried that uploading
it to Google Drive would change the URL, as we had discussed.

However, the "Manage Versions ..." option on Google Drive let
me upload a new version of the file *without* changing the
share URL! Assuming I wasn't hallucinating, this will be a
great way to update both the pdf and the HTML versions as
they change in the future.

Jon

Re: [ANN] Pro Git Reedited 2nd Edition

[Johannes Schindelin]

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

Hi Jon,

On Sun, 24 Jul 2016, Jon Forrest wrote:

> On 7/24/2016 11:27 AM, Jakub Narębski wrote:
> 
> > All right. One issue I have after browsing through changes is that
> > description of changes and their granularity is severely lacking.  "A
> > few more very minor changes.", "More piddly changes.", "should have
> > included this in last commit" are not good commit messages.
> 
> You're absolutely right. I probably should have squashed those commits.
> Those comments aren't really intended for public consumption.
> Since I made many changes per commit, I really couldn't give an
> instructive commit message.
> 
> Now that this edition is done, I plan on following good commit
> practices in the future.

For the record: I found it a good practice to clean up my commits (read:
reword commit messages, split/join commits) *even after* pushing them to a
public repository.

Interactive rebase to the rescue.

That practice is not solely for others' benefit, by the way.

You will most likely find that it not only structures your work better,
you will also find that it turns up things that were forgotten and still
need to be addressed.

Ciao,
Johannes

Re: [ANN] Pro Git Reedited 2nd Edition

[Manlio Perillo]

On Sun, Jul 24, 2016 at 6:07 AM, Jon Forrest <nobozo@gmail.com> wrote:
> This an announcement of Pro Git Reedited 2nd Edition, which is
> a substantial edit of Chacon and Straub's Pro Git 2nd Edition.
> I spent a lot of time tightening it up and maybe clearing
> up some explanations.
>
> The pdf is downloadable at:
> https://drive.google.com/open?id=0B-Llso12P94-Ujg5Z1dhWUhhMm8
>

Thanks for your work.

I have noted a problem when reading the PDF with Chromium: the
anchors/links do not work.

I don't know if this is an issue with the conversion to PDF or an
issue with Chromium.


Manlio

Re: [ANN] Pro Git Reedited 2nd Edition

[Jon Forrest]

On 7/26/2016 2:15 AM, Manlio Perillo wrote:

> I have noted a problem when reading the PDF with Chromium: the
> anchors/links do not work.

I see what you mean. I was able to replicate the problem with Acrobat
Reader on Windows 10. This seems to happen only with internal links - links
to external URLs work fine.

> I don't know if this is an issue with the conversion to PDF or an
> issue with Chromium.

It's not Chromium.

This is going to be tricky to fix. I'm just using the tool chain
that Scott and Ben set up. I've found other issues too that will
be hard to resolve.

Thanks for the report. I guess for now the best thing to do is
to use the HTML version.

Jon

Re: [ANN] Pro Git Reedited 2nd Edition

[Sitaram Chamarty]

On 07/24/2016 09:37 AM, Jon Forrest wrote:
> This an announcement of Pro Git Reedited 2nd Edition, which is
> a substantial edit of Chacon and Straub's Pro Git 2nd Edition.
> I spent a lot of time tightening it up and maybe clearing
> up some explanations.
> 
> The pdf is downloadable at:
> https://drive.google.com/open?id=0B-Llso12P94-Ujg5Z1dhWUhhMm8
> 
> The complete self-contained HTML is at:
> https://drive.google.com/file/d/0B-Llso12P94-U3g1aDBRWjk1Sk0
> 
> The sources for this book are at:
> https://github.com/nobozo/progit2
> 
> I welcome comments.

Hi

While I'm kinda happy to see the chapter on gitolite gone (for reasons
of difficulty in keeping it current at that time), I humbly suggest that
a brief mention of gitolite somewhere in the chapter on "git on the
server" would be useful.

At present gitolite is -- AFAIK -- the only "pure server side", "no GUI"
solution for access control, and has some interesting features that more
"GUI" solutions may not.  It is also (again, AFAIK) used by kernel.org,
Fedora, Gentoo, and several other open source projects as well as many
enterprises.

If you're ok with adding that, I'd be happy to supply some text for your
consideration.

regards
sitaram

Re: [ANN] Pro Git Reedited 2nd Edition

[Jon Forrest]

On 8/12/16 6:11 AM, Sitaram Chamarty wrote:

> At present gitolite is -- AFAIK -- the only "pure server side", "no GUI"
> solution for access control, and has some interesting features that more
> "GUI" solutions may not.  It is also (again, AFAIK) used by kernel.org,
> Fedora, Gentoo, and several other open source projects as well as many
> enterprises.
>
> If you're ok with adding that, I'd be happy to supply some text for your
> consideration.

I appreciate your offer and I don't disagree with what you're
suggesting, but my goal, for now at least, is to keep the same coverage 
as upstream.

If they add something about Gitolite to their next edition, then
I will also.

Cordially,
Jon Forrest

Re: [ANN] Pro Git Reedited 2nd Edition

[Sitaram Chamarty]

On 08/12/2016 08:07 PM, Jon Forrest wrote:
> 
> 
> On 8/12/16 6:11 AM, Sitaram Chamarty wrote:
> 
>> At present gitolite is -- AFAIK -- the only "pure server side", "no GUI"
>> solution for access control, and has some interesting features that more
>> "GUI" solutions may not.  It is also (again, AFAIK) used by kernel.org,
>> Fedora, Gentoo, and several other open source projects as well as many
>> enterprises.
>>
>> If you're ok with adding that, I'd be happy to supply some text for your
>> consideration.
> 
> I appreciate your offer and I don't disagree with what you're
> suggesting, but my goal, for now at least, is to keep the same coverage as upstream.
> 
> If they add something about Gitolite to their next edition, then
> I will also.

Oh ok; I must have misunderstood what "2nd edition" means, or did not read your
original email carefully enough.