In the lab, we use the version control software git to keep track of our code.  All the code is hosted on a server called GitHub.

To run commands on a repository, first cd (change directory) to the folder on the local machine where that repository lives.  You'll see the prompt change to add the word (master) after the directory name.

To check the status of the repository, e.g. whether there are any additions or changes to files in the directory, use git status:

git status

This will display all the local changes -- that is, all the additions or edits to files that were made on the local machine you are working from. Even if git status says "Your branch is up to date with 'origin/master'", there may be changes upstream (i.e., on the GitHub server) that your local machine doesn't know about. To pull in any changes that may have been made to the repository from other machines, use git pull:

git pull

This will pull in any changes. If no changes were made to the central repository since the last pull, git will say "Already up to date."

It's a good idea to get to this state before you start editing code, since it can help you avoid conflicts with existing edits upstream.

Now, let's say you've made edits to the code. To take a snapshot (a "commit") of these changes, you'll first need to stage each file whose changes you want to include by using git add:

git add <filename>

To add all files with changes at once, use:

git add .

(This is not recommended unless you double-check to make sure you want to add ALL files with changes and ALL new files -- i.e., everything that shows up in red text when you run git status!)

To commit the files you've added, use git commit:

git commit -m "Example commit message"

The commit message should be something descriptive of the changes you are committing. For example, "Add vowel space density plotting function" or "Bug fix for randomization procedure".

You can make several commits in a single session; they will all be stored locally as individual snapshots of the code.  When you're ready to make the changes available to all other users/computers, use git push:

git push

This will incorporate all the local commits into the remote "origin" which lives on github.com.

This is likely caused by changes upstream that you haven't yet incorporated into your local copy. You need to incorporate these changes so that your own edits can be layered on top of them. First use git pull:

git pull

This will incorporate the remote changes. Then do a push and accept the default commit message ("Merge branch 'master' of https://github.com...").

What if I do a git pull, and I pull in changes I didn't want?

git reset --hard HEAD@{1}

Pushing changes to free-speech and using branches

The repository blab-lab/free-speech is restricted -- you cannot push changes directly to the master branch. This protects the master branch from bad code changes which would mess up other people's workflows, since free-speech is used by many people for many different tasks.

Instead, you must push changes to another branch, then you can request to merge that branch with the master branch. This is called a "pull request," or "PR". PRs must be reviewed by another person before they can be merged. See this link for a conceptual understanding of branches: https://www.toolsqa.com/git/branch-in-git/

(Preferred option) If you have not edited any files yet, make a new branch and switch to it. Make your changes in that branch, then commit and push.

1. git checkout -b newBranchName
2. [edit whatever files you need]
3. [stage your edits with git add]
4. git commit -m "comment"
5. git push
6. Make a pull request for your branch newBranchName  (eg, gh pr create --web)

If you have edited files but have NOT committed the files yet, use git stash to move those changes to a new branch, then commit and push from that branch.

1. git stash  #puts all changes away - allows you to switch branches
2. git checkout -b newBranchName  # makes a new branch titled newBranchName and switches to that branch
3. git stash pop #pulls your changes back out
4. [commit any/all files you want to push]
5. git push
6. Make a pull request for your branch newBranchName (eg, gh pr create --web)

If you have ALREADY committed the files to the MASTER branch, you need to first move your changes to a new branch, then "reset" the master branch on your local (local computer).

1. git checkout -b newBranchName #makes newBranchName and switches to it. Carries over current commits from master branch
2. git checkout master #switches back to master branch
3. git reset --hard head~10  #reverts the master branch to what it was 10 commits ago (presumably you haven't made more than 10 commits before trying to push)
4. git pull  #restores the master branch to its current state on the server
5. git switch newBranchName
6. git push
7. Make a pull request for your branch newBranchName  (eg, gh pr create --web)

These steps leave you on the new branch you just created. You can switch back to master or another branch (e.g., git switch master) if you need to (in which case you won't see your changes until your new branch is merged).

Git Etiquette

Since we are working with a common codebase, we need to follow some simple conventions to keep things running smoothly.

Don't leave uncommitted changes on shared computers

When you finish working on a lab machine, the repositories should be in a clean state.  Make sure you commit (or trash) any changes so the next person to use the machine doesn't run into conflicts when they try to pull in changes.

Pull regularly

You should git pull on the main lab repos (current-studies, free-speech) at least once a week. This should be totally painless if you've followed the above rule of not leaving uncommitted changes sitting around!

Outside of those regularly-scheduled pulls, you should also pull down a repo before you start editing any code in that repo.

Repositories are for code (or code-like files) only

See this KB doc for more info, but basically, many types of files should not be put in a git repo:

1. data (.mat files)
2. images (figures, pictures)
3. sound files
4. other files such as Powerpoint slides or Word documents
5. Matlab Live Scripts (.mlx) -- these are actually binary files. If you want to keep track of a Live Script, save it as a regular .m file and add that to the repo.

These types of files can go on the Waisman /smng/ drive or M:/ drive instead.