using git

using git

work in progress. if you want more help with this, tag me in a post in the primary gitshow issues page and ask what you'd like to know how to do.

Use your computer's command line for all of this. As a personal aside, on mac I use a great app called iTerm :)

I also highly recommend opening this link in a new window and having it open alongside this page. It's a neat interactive website which explains some core git concepts. I only ask that you refrain from using the 'deleting local branches' method.

Select git terminology and usage

origin

git uses 'origin' to refer to the cloud-based version of the repository, the one which in our case is hosted on github.com.

master

git uses 'master' to refer to the local version of the repository, the one which is on your computer. Unfortunately the term 'master' is also used in git's 'branches' terminology, so it's important to know the context in which 'master' is being used. More on this later.

clone

this copies a repository from origin into a directory on your computer. you should only need to do this once. after cloning, if you need to update master with changes someone else made to origin, see 'pull'.

1. Go to a given repository's url
2. click the green 'clone or download' button
3. copy the entire url within
4. open a terminal window
5. point the terminal session's working directory to a folder you want to add the repo to. i.e.

cd /path/to/desired/directory
# press enter/return

Note: for myself, I prefer to keep all my repos in the same directory that my terminal defaults to on open (in my case, my OSX home folder '/mp'. note that you can also change the default working directory in terminal and iTerm...

6. type 'git clone ' (with the space at end) and paste the url

git clone https://github.com/dispersionlab/gitshow7.git
# press enter/return

Should take up to a minute...

git log

this is the repository's version history. it can receive many arguments to provide with you so much detail.

Before you continue, know that unless you've configured it otherwise, git will report the log using the vi editor. So to see more entries in the log, hold the enter or return key, and to exit the log, press q

# show the basic version history
git log

# show the version history with names of files changed
git log --stat

# show the git log UI (I don't personally like it for all situations, but sometimes its helpful)
gitk

commit

a commit is a user-generated snapshot of all the changes made to file(s) in the repository since the last commit. It includes many details, including the committer's name and email, the date, the commit hash, list of new/modified/deleted files, deltas, and more.

git commit -am "message about your commit"

important: in special circumstances, you may have added a new file, such as discussed in this issue thread here, and so you will instead need to first add the file to git's tracking system:

git add /path/to/new/file/to/track
# press enter/return

git commit -m "message about commit"

deltas

Git uses a compression method called delta encoding. Rather than store entire full versions of files at each commit, it only stores what changed from the previous commit to the current state of the repository. Deltas are included in a commit.

commit hash

This is a 40-character unique string generated by git when you commit, and is often abbreviated by the first 7 characters. See for example, the commit hash 4f650ba in repository gitshow2

push

this is the upload method. when you push, git takes your local deltas and adds them to the front of the version history (itself a list of deltas) in origin.

git push

pull

Pulling is the inverse of 'pushing'. It is the action of updating your master with any changes made to origin by someone else since the time you cloned, or since the last time you pulled. If there are changes in master that haven't been committed, git will refuse to pull.

git pull

merge conflict

Sounds scary, can be annoying, but its one of the most important features in git. A merge conflict arises when you try to pull, but a file you changed has already been modified at origin by someone else. Git throws a merge conflict to prevent applying someone else's changes to your version, and instead inserts conflict markers into the document(s) in question. Your task then becomes to open the document (ideally in an editor that can handle git merges, makes like way easier), and resolve the versions by either accepting your change(s), their change(s), or both. Then you save the file, and commit to complete the merge.

Most code editors will have a github or merge package available to help with this, and you can configure git to use that editor instead of vi (which can be annoying unless you're familiar with using it already).

• Visual Studio Code Insiders has a great built-in merge conflict mode (it's what I use)
• Atom has the github package, here's an entry on merge conflicts
• Sublime Text also has a mode for resolving merges

By the way, the way git annotates text files with merge conflict markers is one of the primary reasons I opted to switch using Max/MSP for the git show experiment, since the .maxpat data structure doesn't play nice with these markers.

branches

ah branches! a branch refers to a specifically named range of deltas in the version history. all repos have at least one branch, named (unfortunately) the master branch (remember this term usage is distinct from the 'master' used to refer to the local version of a repo). Branches is where the git show experiment can really get interesting, as you can use branches to:

• make experimental changes to a file without worrying about losing progress
• go back in time to an earlier commit and use an older version of a file take a different creative path with it.
• merge ideas from a file in one branch into a file in another branch.

# list branches available locally & see what branch you're on (indicated by an asterisk *)
git branch --all

## note that 'git branch --all' might return some branches prefixed with remotes/origin/, 
## these are branches created by others and your master is not currently tracking them. 
## To switch to one of these and begin tracking, run
git switch --track remotes/origin/nameOfRemoteBranch

### ... and then you can run 'git branch --all' to confirm that the remote branch is now being tracked by master. 

# switch to a different branch
git switch nameOfBranch

# create a new branch starting from the most-recent commit, on the branch you're currently on. 
git switch -c nameOfNewBranch

# create a new branch starting from an earlier commit made by anyone (you could find the hash using 'git log')
git switch -c nameOfNewBranch 40characterCommitHash

#### Important: Origin will not automatically track any branches you've created. You must instruct it to do so. 
git push -u origin nameOfNewBranch

# merge changes from one branch (we'll call it 'source') into the branch you're currently on
git merge source