Small, Smart, Often

• Small: Commit with every small, logical, well-test block of code. For example, when you have completed one function or method, and tested it very well, commit it. Another example, you fix one bug, you test the fix very well, commit it. One of the most important mindsets you must have as a programmer is to think in small, modular, "bite-sized," logical portions. This is how we write functions, fix bugs, approach all software design, and also how we commit. As a larger example, imagine you are starting a new module, beginning with an empty file. The correct committing process would be something like this...
  • Create the file. Add and commit with the message, "initial commit."
  • Add your comment header, commit with the message, "added comment header."
  • Stub out the basic functions you know you will write, or stub out the class, or whatever stubs you think you will need. This does not have to be complete, and should only be a few basic stubs (no code in the function stubs). Commit with a message like, "stubbed out basic functions: function1(), function2(), function3()."
  • Write the code for one function, test it thoroughly. Commit with a message like, "implemented function1() which does this and that and will be used to do this, called by that."
  • Write the code for another function, test it thoroughly. Commit it with a message like, "Implemented function2() which does this and that and will be used to do this, called by that."
  • You notice a bug in function1(), fix it, test it thoroughly, commit it with a message like, "Fixed bug in function1(), the bug was in line # and was causing this and that problem because of this and that mistake."
  • Write the code for another function, test it thoroughly. Commit it with a message like, "implemented function3() which does this and that and will be used to do this, called by that."
  • Keep going...


• Smart: Committing smart means to write descriptive, intelligent, meaningful messages.
  • Never write messages like, "done," "fixed bug," "added css."
  • Always detail what you did, how you did it, why you did it.
  Think of your commits as "telling the story" of your development process. Another programmer should be able to read your commits and know everything you did, why you did it, how you did it, and completely understand your thought process like reading a story.


• Often: Committing often is related to committing small. If you commit small, you will end up committing often. If you are not committing every 15-45 minutes of development time, you are likely not committing often enough. This is a rough guide, and assumes an experienced programmer moving at a good pace. If you program slower or faster, this timing will change. For example, if it takes you 2 hours to track down one bug, and an hour to fix it, you will be committing slower. Conversely, if you are just starting a new module, you may make 5 commits in 5 minutes as you get started. The point is, you shoud be committing relatively often.

What to Commit and Not Commit

Do not commit...
• Executables: The purpose of a repo is for someone else to get your code and run it themselves. No one wants your executable. Also, never run someone else's executable unless you trust the source.
• IDE directories/files: No one wants your dev environment, they want your code for their dev environment.
• OS files: No one wants your OS system files (Mac people I'm looking at you).
• Data files: Usually we don't commit data files, but sometimes we do. It depends on the application and reason for including data files. Follow this restriction intelligently.
• Sensitive information: For example: .htaccess files, files with passwords in them, confidential business documents, etc.

Do commit...
• Code: All the code required to build/run your project.
• README files: Include descriptive README.md file(s).
• .gitgnoire: No one wants your OS system files (Mac people I'm looking at you).
• Libraries: Any library needed to run your project which another person may not have by default, or is not installed automatically by your application itself. Do not commit libraries, by default, only if they are needed because you know the user is not likely to have them.

Failure to commit smart, small, often in class will result in your work being rejected, and assigned a grade of zero. Failure to commit smart, small, often on-the-job will result in getting fired. Take this seriously.