GitHub Best Practices

Here are a few recommendations to help get the most out of GitHub at NC State.

Make use of Organizations

GitHub Organizations are a great way to collaborate on projects, manage permissions across a large number of repositories, and ensure that data is not lost when a person leaves the university. Organization owners can set up permissions to all repositories in the organization for members, which can save a lot of time and effort for groups with a large number of repositories. You can also make use of Teams to do group based access control within the organization.

Additionally, since the repositories are owned by the organization rather than a user account, the repository and all access controls are retained even when people leave the university. We recommend using an organization for any repository that impacts more than a single person. Organizations are free to create, and you can make as many as you need.

When naming your organization, you should choose a name that describes the purpose of the organization, or the group of people it represents. Keep in mind that there cannot be multiple organizations with the same name, so avoid common names like “Project” or “Homework”. The GitHub service team reserves the right to rename organizations if deemed necessary.

Avoid Committing Large Files

In order to ensure reliable performance of the GitHub service, we limit the size of git objects that can be stored in GitHub. Currently the limit is set to 100MB, which means that only files 100MB and smaller can be committed to a git repository and pushed to GitHub. Attempting to push commits that contain files larger than 100MB will result in an error, and the commits will be rejected.

While there is no fixed limit for the size of an individual repository, we enforce soft limits by warning users who are consuming an abnormally large amount of disk space. Binary files such as images, zip files, Word Documents, PDF files, etc, are better stored in an alternative storage location, such as AFS or Google Drive.

Secure your Account with Two-Factor

Enabling two-factor on your account adds an extra layer of security to your account. Even if your username and password are compromised, a two-factor code can prevent an attacker from accessing your account. GitHub accounts can optionally enable two-factor via the User Setting menu under Security.

Use SSH keys instead of HTTPS

The NC State GitHub deployment runs in private mode, which means that all interaction with the service must be authenticated. Needing to provide your username and password every time you want to push to GitHub can be annoying and time consuming. When performing git operations on an HTTPS git URL, you will be prompted for your credentials each time.

By setting up an SSH key and using the SSH git URL, you can simply push and pull immediately without needing to supply credentials. If you have two-factor enabled on your account, you MUST use this method because the HTTPS git URL has no way of supplying the two-factor code.

Make Effective use of Branching

Unlike other version control systems, creating branches in git is cheap and quick. Making effective use of branching allows you to very quickly work on a new feature or bug-fix and very easily compare the changes you’ve made to the main development branch, even across multiple commits. Utilizing branches also makes collaboration with others much easier, since everyone can work on a different branch and then merge changes in.

GitHub allows you to easily visualize merges in the web view via Pull Requests. In a Pull Request, you can see all the commits that will be merged, discuss the changes with your team, and view a summary of all pending changes.

You can even protect certain branches in GitHub to prevent users from pushing directly to the branch. This workflow is great for large projects where changes need to be approved before they are merged into production.

Use .gitignore to Prevent Tracking Files

The .gitignore file is a special file in your git repository which will cause git to ignore any file whose name matches what’s in the file. This can be very useful to prevent accidentally committing files containing passwords or access keys, which should be kept out of the commit history. Setting up a gitignore file at the start of your project can save you from leaking a password down the road.

Write Thoughtful Commit Message

A well crafted commit message can be very useful when working on a project. The diff will tell you exactly what changed in a specific commit, but only the commit message will tell you why. One of the most important skills you can learn when learning git is how to write a good commit message.