Basics of using git and GitHub (on a mac, for Matlab/Python)

Contents

  1. Introduction
  2. Objectives in getting to grips with git
  3. Technical setup/context
  4. Main steps I followed to get a working system
  5. Further reading

1 Introduction

I write a fair amount of computer code to support my research and teaching. Most of it is in Matlab, and some of it in Python. Some of my coding archives are very well organised, and some leave a bit to be desired.

In a bid to do better, I recently started using git to help manage and maintain my code. Simultaneously, I wanted to get to grips with how to integrate local version control (i.e., git) with publishing code online via GitHub.

As someone who has picked up coding skills and use of the command line along the way, as it were, I decided to write down exactly what I did to get myself set up and working, and to share it here. I hope the info is easy to follow for those who aren’t expert bashers.

2 Objectives in getting to grips with git

My objectives in getting to grips with git are to:

  1. Start using git on my local machine to manage certain pieces of code, projects, and datasets. This is for:
    • Version control
    • Becoming a better coder
  2. Synchronise certain pieces of code, projects, and datasets with my GitHub account to share items for their own sake, and when associated with research publications (mainly in a ‘push’ fashion, i.e., from my local machine to GitHub). This is for:
    • Openness and transparency
    • To allow others to easily use and/or adapt my code
  3. Learn how to fork/branch other people’s repositories (i.e., in a ‘pull’ fashion, i.e., from GitHub or elsewhere to my local machine)

3 Technical setup/context

This is my technical setup:

  • Using a mac, and MacOS 13.6.7 (Ventura)
  • Using iTerm2 as my command-line interface (https://iterm2.com/), or CLI, in lieu of Apple’s Terminal application
    • It has a few extra features that I find useful, but the regular Terminal application is also fine
  • Homebrew is already installed (https://brew.sh/), to enable easy use of the command-line to install useful software packages from the web (it’s a package manager for such installations, providing a way to install, upgrade, configure, and remove software packages)
    • The frontpage of https://brew.sh/ provides a single-line command you can copy/paste and execute in iTerm2 (or whichever CLI you decide to use) to install Homebrew on a mac

4 Main steps I followed to get a working system

Step 1: Install ‘git’ via the command line

Use iTerm2 and Homebrew to install ‘git’ on my local machine (https://git-scm.com/download/mac), by executing

brew install git

and set up your name/email so that they will appear against any repositories you add/manage/update (see below). Do this by executing

git config --global user.name "Your Name"

and

git config --global user.email "your@email.com"

where you replace the items in quotes as appropriate.

Step 2: Configure ‘git’ via the command line (default branch naming, system-wide .gitignore)

Now, adjust the global git settings so that the default branch naming used by all local repositories is main (which is now the default within GitHub), and not master (which was the previous GitHub default). This makes it easier to do the first push synchronisation from local–>GitHub without having to faff around with branch renaming etc. Execute this to make it happen

git config --global init.defaultBranch main

Next, adjust the global git settings to use a single, global .gitignore file for all repositories, which ensures that git doesn’t pick up system files and temporary Matlab or Python files and include them in git version control and any subsequent push to GitHub. Note that you can still add separate/custom per-repository .gitignore files as required.

Steps:

  1. Using iTerm2, navigate to the root directory in your home folder
    cd ~/
  2. Run
    ls -al

    and examine the list of files to check that you don’t already have a .gitignore file in your home folder

  3. Assuming there is no existing file, create one. There are various ways to do this, e.g., using the inbuilt ‘nano’ text editor works quite well. For this example, I will assume you have a good code editor installed (e.g., Sublime Text is nice). Therefore, we first create the file via
    touch .gitignore

    and then we’ll open it with our favourite code editor, via

    open -a 'Sublime Text' .gitignore

    This should launch the app and give you an empty document (called .gitignore). Add a short comment at the top of this new file to identify what it is, e.g.,

    # Global .gitignore file for all repositories within the local account of: 'USERNAME_LOCAL'

    where USERNAME_LOCAL might be your local account name.
    Then, add in the file extensions of any files or folders that you know, for sure, you won’t ever want added to a git repository, each on a separate line. Since I’m on a mac and I use Matlab and Python, I combined items from the .gitignore templates here, here and here into this single .gitignore file. I’ve made this file available via: https://github.com/self-noise/Using-git-and-GitHub
    To use my prebaked file, either download the file, copy it into the root of your home directory, and rename it to .gitignore. Or, having already created your .gitignore file, just copy/paste the content of my file into your file, before saving and exiting.

  4. Now you need to tell git that you have a ‘global’ .gitignore file which it needs to check every time it sets up a new repo, rescans an existing repo for file changes, or adds new files to an existing repo. Do this by executing the command
    git config --global core.excludesFile '~/.gitignore'

    The result of the command should be that nothing appears to happen. However, you can check if the file has been added as a global .gitignore by running

    git config --global core.excludesFile

    which should then print out something like

    ~/.gitignore

    which confirms that git knows about the file, and that it is located in the root of the current home directory.

Step 3: Install the GitHub command-line interface software package

Use iTerm2 and Homebrew to install the command-line based GitHub software package, which will facilitate easier interfacing between local repositories and my GitHub account. Steps to follow, as listed here, are:

  1. Execute the following to install the latest GitHub package via CLI
    brew install gh
  2. If everything goes to plan, you should now have a new command available, gh, which will allow you to work directly with GitHub via your CLI

Step 4: Set up a local test folder, make it a git repository, and learn git basics

Create an empty folder, somewhere within your home directory structure, and add a few files to it (e.g., Matlab or Python scripts) with which to test things out and get used to the commands involved in using git. On my machine, I placed this somewhere like

~/Coding/MATLAB/Library/MyCode/TestFolder/

and I added a few .m files.

Now let’s do set the folder up as a repository (aka, repo) and set up basic version control, using git:

  1. Using iTerm2 again, navigate into your test folder, then execute the following to set up the test folder and contents as a new local repository (i.e., git-managed folder), which enables git version control
    git add .

    At this stage the files are added to the git ‘staging area’ , which means that git knows about them, but they haven’t yet been committed to the current main branch
    Note: Having already set[LINK] up a global ~/.gitignore you shouldn’t run in to problems with git picking up extraneous system files (e.g., .DS_Store on a mac) that you don’t need to version control and adding them to the repo

  2. Commit the files that have been added to the staging area, whilst adding a short note to the log to explain why has been done, via executing
    git commit -m 'Initial setup of files to be version controlled'

    This means that git has an up-to-date record of these files as constituting the current main branch of

  3. Make a change to one or more of the existing files, and/or add a new file to the folder. Now once again run
    git add .

    which should give you a feedback dialog listing the changes that git has identified within the repo.
    There’s a useful command to know that summarises the status of the current repo, and now is a worthwhile time to try it, by executing

    git status

    If you are happy to commit the most recent changes, run

    git commit -m 'File changes and additions'

    where the text in quotes should be a brief account of changes you made to the repo since the last commit
    Now again running

    git status

    will give you feedback to say that the repo is fully up to date with all changes

  4. You can already do a lot of useful things with this simple set of tools, but if you want to learn about other things you can do using git on this new repo, such as branching, there are plenty of great resources elsewhere

Step 5: Create an empty repository within your GitHub account

Set up an empty repository within your GitHub account, ensuring that you DO NOT add anything to the new repo, for the time being. This means DO NOT add a .gitignore file, NOR a LICENSE file (we can add these later, once we’ve set up a synchronisation with the appropriate local repo.

[MORE TO BE ADDED]

Step 6: Connect local repo to GitHub repo

Connect your dummy local folder/repository to the new empty repository on GitHub, using the gh tool available via CLI.

[MORE TO BE ADDED]

5 Further reading

[1] TLDR Legal: Summary of software licenses in human-readable language (including licenses available as default within GitHub, e.g., MIT, GPL, etc)

[2] iTerm2 CLI: List of useful commands for the iTerm2 command-line interface app

[3] Learn git in 15 minutes: Nice short YouTube video which summarises key things to get you going

[4] .gitignore on Windows