[ANN] Pro Git Reedited 2nd Edition

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

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

[...]

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,

On Sun, Jul 24, 2016 at 6:07 AM, Jon Forrest <nobozo@gmail.com> wrote:

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

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

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.

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

On 07/24/2016 09:37 AM, Jon Forrest wrote:

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

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

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

On 08/12/2016 08:07 PM, Jon Forrest wrote:

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

Re-added git mailing list

On 24 July 2016 at 17:57, Jon Forrest <jonf@captricity.com> wrote:

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

Good.

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

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

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.

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

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

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.

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.

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?
 

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,

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

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

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.

I'll check that.

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.

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

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.

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

Jon

Hi Jon,

On Sun, 24 Jul 2016, Jon Forrest wrote:

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

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