Version Control Tutorials

The below tutorials are all focused on version control (especially Git and GitHub). See sub-headings for more specifics! Acronyms used in this page include:

Git Command Line Snippets

There are a few Git operations I need infrequently enough that I haven’t committed them to memory but would like an easy place to quickly reference as needed. Each tab below separates Git commands useful in different circumstances. Note that the tab order–and content within each tab–is ordered based on how often I need to refer to these snippets so I hope that doesn’t diminish their usefulness to you.

Failed Push/Sync Due to Too Much Data

If you commit too much data on your local repository, your push/sync to GitHub will fail. You can force your machine to allow a larger amount of data in a single push/sync if need be. Ideally, you’d avoid committing too much data at once but this solve works if you forget.

Allow a single push/sync to include more/larger files
git config http.postBuffer 524288000

Changed Remote Name

If you change your GitHub repository’s name after cloning it, you may get a warning in your IDE that your ‘remote has moved to a new location’. Many IDEs are savvy enough for this not to cause a real error but it’s good practice to tweak things so that the only warnings you get are the ones to which you want to pay attention.

Update existing local repository with new remote URL:
git remote set-url origin {new URL}

Branch Housekeeping

Once you are done working in a branch (i.e., have merged it with ‘main’), there are a few good houskeeping steps to follow:

  1. In your IDE, switch back to ‘main’ and pull/sync
  2. Delete the branch in your remote repository
  3. Delete the branch in your local repository
    • git branch -d {branch name}
  4. Update your local repository’s list of the branches it thinks are in your remote repository
    • git remote update origin --prune

Check Current Settings

It can be helpful to see what your current Git settings are. Fortunately, there’s an easy way to check your global Git settings on your machine.

List Git information on your computer
git config --global --list

Credential Caching

On some remote servers (e.g., those used by NCEAS), you must specify how long you want your credentials to be “cached” (i.e., remembered). It is a pain if you forget to cache your credentials as–in the worst case–it may mean that you’d need to make a new PAT if your old one is not cached and you didn’t save it elsewhere.

Cache your credentials for 10 million seconds
git config --global credential.helper 'cache --timeout=10000000'

Conventional Commits

I use Git to preserve the history of files in the vast majority of my projects but I am largely self-taught and thus feel like I periodically stumble onto fabulous features I didn’t know existed. For example, I was introduced to Conventional Commits which is a system for making more informative commit messages in version control systems.

I’ve long appreciated that “update” is not an ideal commit message but it can be hard to know which files should be staged into a commit or how much rambling information is useful in the long term. I’ve really enjoyed using this system to formalize both the frequency of my commits and the content of the associated messages.

Explanation

A conventional commit is one that uses one of the allowed “types” followed by a colon and then a short description of the specific content of that commit. As an example, your commit might look like: docs: improve readme. Making sure a commit fits only a single ‘type’ (and that all of the changes for a particular ‘type’ are in the same commit) has been a really useful scaffold for me. If it’s a breaking change you put a ! after the ‘type’ but before the : (e.g., feat!: remove tip page from site).

I’m doing my best to be consistent in using this system going forward but this GitHub repository is one good example of my approach to this method.

Available ‘Types’

For reference, here’s the full list of official ‘types’ (and one bonus that I use sometimes). Note that I added fun symbols for each type that are not official.

Type Symbol Description
build

Changes to build system or external dependencies (e.g., Quarto extensions, etc.)
ci

Changes to continuous integration (“CI”) operations (e.g., GitHub Actions, etc.)
dev

Experimental changes that you may want to revisit in the future. This is my un-official addition!
docs

Changes to documentation
feat

Changes that introduce a new feature
fix

Changes that fix a bug
perf

Changes that affect (improve) performance
refactor

Changes that neither fix a bug nor add a feature. Used when the output of the code is unchanged but the way in which that output is reached has changed
style

Changes that do not affect the meaning of the code (e.g., white space, formatting, etc.)
test

Changes that create or modify tests