Git smart! 20 essential tips for Git and GitHub users

Smarter cloning, forking, merging, and branching with Git and GitHub

1 2 Page 2
Page 2 of 2

Git/GitHub tip No. 18: Write informative README pages

In tip No. 11, I sent you to the README page of jquery/jquery to find out about the project. Write good README pages for your projects, and you won't regret it.

README has been an established convention in software development since at least the 1960s, when I saw my first one printed out IN ALL CAPS on the green-and-white paper that was wrapping a stack of Hollerith cards intended to be run on an IBM 1640. I saw many more in the 1970s, on every conceivable media and operating system, when I worked on DEC minicomputers and large IBM mainframes. See alsoREAMDE.

Git/GitHub tip No. 19: Use Markdown

Early README files IN ALL CAPS were more than a little basic. The current standard for formatting README files isMarkdown, specifically GitHub Flavored Markdown. I used to see README files in HTML, but the practice seems to be fading.

Git/GitHub tip No. 20: Convert your older repos to Git

Of all the tips I've listed, this one might be the hardest to implement, both technically and politically. Politically it's hard because programmers are by nature conservative about their tools. That needs to be addressed with training (see tip No. 5).

It's technically hard to convert big, old repositories with millions of lines of code, tens of thousands of commits, and thousands of tags because the processes for this use a metric ton of memory. I have had decade-old CVS repositories that would only convert on large or extralarge Amazon EC2 instances, and they still took days for the conversion to complete. If you're converting from Subversion, try using svn2git. If you're converting from CVS, consider git -cvsimport and cvs2git.

Copyright © 2014 IDG Communications, Inc.

1 2 Page 2
Page 2 of 2