27 essential tips for Git and GitHub users

Smarter cloning, forking, merging, branching, documenting, sharing, and automating with Git and GitHub

1 2 Page 2
Page 2 of 2

Git/GitHub tip No. 12: Use editors and IDEs that “git it”

If you’re barreling along on an edit only to discover, when you go to check it in, that someone else has been working on the same code as you have, you’re likely to become frustrated. You can avoid or at least minimize that frustration by using an editor or IDE that integrates Git and actually tells you that the code you’re viewing has new commits that you should pull, and what the new commits are supposed to accomplish.

Git/GitHub tip No. 13: Fork a repo

Forking a repository means creating your own writable server copy of a repo—that is, creating a fork in the road. Recall that we clone a repo (see tip No. 1) to make our own client copy of it. If it’s a public repo for which we do not have commit privileges (see tip No. 11), then the easiest way to contribute our changes is to first commit them to our own fork of the repo on the server via the fork button on the original GitHub project. Then we can issue a pull request (see tip No. 16) to the owners of the forked repo so that they can test and possibly use our contribution. It’s confusing at first, but it gets easier. See, for instance, this book section on contributing to a small public project.

Git/GitHub tip No. 14: Watch projects

When you fork a project, you’ll most likely want to know what’s happening in the upstream project. If so, watch the repo. If the update chatter annoys you, unwatch it. If you notice changes that affect you, fetch and merge the upstream commits.

Git/GitHub tip No. 15: Follow friends

GitHub suggests that you follow GitHub employees “in a non-creepy way.” You should also follow people from projects that interest you, and that might lead you to other projects that interest you. I followed dmethvin on GitHub—but that’s not creepy since we’ve worked together on and off since he was at PC Tech Journal, and now he’s president of the jQuery Foundation.

Git/GitHub tip No. 16: Send pull requests

In tip No. 13, we talked about forking a GitHub repository. The way to get the upstream repository (the one you forked from to make yours) to incorporate some or all of your changes is to send them a pull request, following this guide.

Git/GitHub tip No. 17: Create and resolve issues

All software has bugs. Many software projects use a separate bug-tracking system, but some use the Issues feature in GitHub. You can be useful to a project by reporting an issue, and even more useful by solving one.

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 also REAMDE.

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 is Markdown, 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.

Git/GitHub tip No. 21: Use GitHub project boards

GitHub project boards, which can belong to a user, organization, or repository, contain cards organized into columns. The cards may be issues (see tip No. 17), pull requests (see tip No. 16), or notes; the columns may be anything that is useful to the project. For example, the TensorFlow PR queue contains issue cards in columns classifying the issue status: assigned reviewer, changes requested, approved, merged, and closed/rejected. 

Git/GitHub tip No. 22: Automate your workflow with GitHub Actions

GitHub Actions allow you to create workflows, such as continuous integration (CI) and continuous deployment (CD), that are triggered by GitHub events such as code pushes, pull requests, and issue creation. Actions may be used instead of separate automation servers such as Jenkins.

Git/GitHub tip No. 23: Build and publish packages

GitHub Packages is a software package hosting service for NPM, Docker, Maven, Gradle, NuGet, and RubyGems. A GitHub package inherits its permissions from the repository to which it belongs. You can integrate GitHub Packages with GitHub APIs, GitHub Actions (see tip No. 22), and webhooks. You can install packages as dependencies in your projects, and you can publish packages for use by anyone authorized to access the repository. 

Git/GitHub tip No. 24: Check and resolve your security advisories and alerts

Every repository on GitHub has a security tab that lists the repo’s security alerts, advisories, and policy. GitHub sends security alerts when it detects vulnerabilities affecting your repository. A vulnerability is a problem in a project’s code that could be exploited to damage the confidentiality, integrity, or availability of the project or other projects that use its code.

Advisories are drafts where you can privately discuss, fix, and publish information about security vulnerabilities in your repository’s code. A security policy communicates how your community can securely report security vulnerabilities for your project. GitHub monitors your project dependencies and automatically opens pull requests to update dependencies to the minimum version that resolves known vulnerabilities. 

Git/GitHub tip No. 25: Scan your code for vulnerabilities

In addition to acting on security alerts, you should also scan your code for vulnerabilities. Semmle’s semantic code analysis engine, CodeQL, treats code as data. In addition to running CodeQL directly on your repositories, you can run it from IDEs such as Visual Studio Code and CI/CD services.

Git/GitHub tip No. 26: Publish your documentation pages

GitHub Pages is designed to host your personal, organization, or project web pages from a GitHub repository, in a blog-like way. To enable Pages for a repository, go to the settings for the repository, scroll down to the GitHub Pages section, and choose either a branch or the /docs folder of the master branch.

You can also choose a Jekyll theme for your pages. Note that because GitHub Pages supports the Jekyll static site generator, you can write your documentation in plain text or Markdown; in other words, you don’t need to write HTML, although you can use HTML if you wish. You can also use a custom domain for a GitHub Pages site simply by adding a CNAME file from your repo settings and adding a CNAME record to your domain settings at your DNS provider.

You get one site per GitHub account and organization, and unlimited project sites. To create a site for your account, create a new repository named <username>.github.io, where <username> is your GitHub user or organization name. Then start committing content to that repo.

Git/GitHub tip No. 27: Collaborate on documentation in wikis

Every GitHub repository can contain a wiki, which is intended to host documentation, examples, support, and mission statements beyond the high-level description in the standard README.md file. By default, only people with write access to your repository can make changes to wikis, although you can allow everyone on GitHub to contribute to a wiki in a public repository. You can enable or disable wikis for a repo in the Features section of the settings page, and you can optionally restrict editing to repository collaborators.

Git and GitHub resources

Copyright © 2019 IDG Communications, Inc.

1 2 Page 2
Page 2 of 2