Re: [oll-user] Git for dummies

[Marc S. <ma...@ou...>]

I'd like to step back and say a few things about the "big picture" 
here.  There are any number of "Git for dummies" tutorials out there 
that you should should probably spend some time with, but having gone 
through this pain myself recently with MuseScore, I can tell you the 
devil is as likely to be in the details as in the concepts, because 
every project structures things differently.

Ideally, we'd all come to this (or any project) with a basic handle on 
how Git works from the various tutorials that float around out there, 
and the project would provide a "Git workflow" document that detailed 
the specifics in a manner that would be clear enough to anyone with a 
basic familiarity with Git.  I think the current Git workflow document 
we have here is a start, but doesn't go far enough, so maybe we need to 
work on that.

First, though, here's my bare bones and probably a bit naive nutshell 
description of Git as it applies to GitHub-based projects specifically:

A project has a main repository (repo) stored on GitHub that is the one 
we are referring to as "upstream".  This one you will *read* from (via 
"git fetch upstream") whenever you need to get updated files contributed 
by others.  You will never probably write to this directly.

When you first join a project, you start by creating a "fork" of that 
repo, which creates your own personal copy of that upstream. Your fork - 
which we are calling "origin" - is *also* stored on GitHub, and this is 
what you will *write* to (via "git push") when you want to make your 
work available to others.  After pushing to your fork, you then issue a 
"pull request" to the owner of the upstream repo that says "I have 
pushed changes to my fork, please merge them into the upstream repo".  
That is how your changes become available to others, and how their 
changes become available to you - by being merged into the upstream repo.

All of this is on GitHub.  You will work, of course, on your own 
computer.  So you do a "git clone" of your fork, which creates a local 
copy of everything.  This is your own personal sandbox; you play with 
these files however you like, including adding new ones. Every so often, 
you decide things are at a state where you want to take a snapshot of 
your current sandbox.  You do this via "git commit".  After one or more 
of these commits, you might decide you are at a point where you feel 
these should be written to your fork on GitHub, so you do as "git 
push".  After one or more of these pushes, you might decide your work is 
ready to be shared with others, so you issue a  "pull request" (that is 
done on GitHub). Every so often, you will also decide it would be good 
to grab the work others have been contributing.  So you do a "git fetch 
upstream".  Because of the details of how git manages version control, 
you have to also do a "git rebase" to fully incorporate their changes 
into your sandbox (this is the step hardest to fully grasp, I find).  At 
that point, you can in principle continue working, do more commits, more 
pushes, and pull requests, and the cycle continues.

That's the overall flow of this and other projects that use GitHub. When 
you read the various Git tutorials out there, you won't see much talk of 
forks and pull requests - that's more of a GitHub-specific thing, I 
guess.  The Git tutorials focus mostly on branching, which I didn't even 
mention here.  Because that's when you start getting into the details 
different projects handle differently, and where I think the workflow 
document for this project could stand to spell things out in more detail.

Anyhow, I hope this helps.

Marc