Guidelines for the Github rookie

Or, how to keep your repos from looking like s***

A sloppy Github repository

Intended audience

Users who are *very* new to Github repository management and/or students at Holberton School.

Environment

Linux vagrant-ubuntu-trusty-64 3.13.0–107-generic #154-Ubuntu SMP Tue Dec 20 09:57:27 UTC 2016 x86_64 x86_64 x86_64 GNU/Linux

Distributor ID: Ubuntu
Description: Ubuntu 14.04.5 LTS
Release: 14.04
Codename: trusty

Wondering how to generate the above information? In your terminal, type man lsb_release and man uname and find out!

Issue 1.1: Garbage files appearing in repository

Sloppy Github repositories show a lack of attention to detail and detract from your otherwise awesome code. The best way to manage your files and prevent garbage files like the ones in the above screenshot from showing up is by creating a .gitignore file.

Solution: Create a customized .gitignore file

Your .gitignore file can be customized in any number of ways. This tutorial outlines a .gitignore file used specifically for projects completed as part of the Holberton School curriculum. In order to customize, I listed out the conditions that I wanted to filter out:

  1. executable files named during compilation that do not have an extension (i.e. program_name)
  2. emacs generated autosave backup (i.e. filename~)
  3. emacs generated modified files (i.e. #filename#)
  4. Holberton-provided _putchar.c program and files containing ‘main’ in name
  5. default executable file (i.e. a.out)
  6. object files (I added this later when we studied static libraries)

To learn more about how .gitignore files work, check out this support article on Github or type man gitignore in your terminal.

The trickiest condition to check for would be the first — executable files that do not have an extension. In order to do this, I first ignored all files, then unignored any files with extensions and files inside subdirectories.

# Ignore all
*
# Unignore all with extensions
!*.*
# Unignore all dirs
!*/

After that, the remaining conditions are pretty straightforward:

# Ignore emacs autosave~ and #modified# files
*~
**/*~
**/\#*
# Ignore main files
**/*main.c
# Ignore object files and libraries
*.o
*.ko
*.obj
*.elf

To test whether or not my file is working, I run the git status command. The file is successfully filtering files as long as files included in your .gitignore file no longer show up as being untracked. I noticed that _putchar.c file and a.out were still showing up so I added one more line to my file that simply outright named them as files to ignore.

# ignore _putchar.c and a.out
**/_putchar.c
**/a.out

Issue 1.2: Unhelpful commit messages

Visitors to your Github repository should be able to see some type of progression of logic and or thought through your commit messages. It’s also never too late to start honing good commit message habits. Imagine if you were one of over a hundred contributors to a repository — those other 99 contributors will probably refer to your commit message as an explanation of what changes you’ve made in your files.

Solution: Follow a published format for committing files

When I first started out at Holberton, my commit messages were just descriptions of the task.

I then consulted Google and found this great guide that summarizes the git commit man page as well as other resources into the below seven rules — definitely check out the article for a more in depth read!

The seven rules of a great Git commit message
Separate subject from body with a blank line
Limit the subject line to 50 characters
Capitalize the subject line
Do not end the subject line with a period
Use the imperative mood in the subject line
Wrap the body at 72 characters
Use the body to explain what and why vs. how
One clap, two clap, three clap, forty?

By clapping more or less, you can signal to us which stories really stand out.