Fun with Git, Redux

[John Ralls]

> On Aug 27, 2015, at 3:34 PM, David T. <sunfish62 at yahoo.com> wrote:
> 
> I apologize in advance for my utter inability to understand this whole Git realm.
> 
> I have a sincere desire to help with the documentation, but what I would like to do is focus on the writing, and not with the Gitting. Unfortunately, instead of writing or editing documentation, I spend hours trying to understand the simplest of steps in the Git world, and this has me exceedingly frustrated.
> 
> Let me begin by saying that I am using a Mac on OS X 10.10.5, and the Git tool I am using is SourceTree 2.0.5.2. I am not a programmer, but I used to think I was, back in the days of Visual Basic.
> 
> After my patches from February resulted in an insurmountable (for me, at least) conundrum of patches that would not apply, I completely nuked my local copy of the docs and re-cloned from github, as per the Writing Documentation page. 
> 
> With a fresh copy of the docs, I began by creating new branches—one for each bug I was working on. I named each branch with the bug number to keep things straight. This was based on advice I received here. 
> 
> I then worked on Bug A in file A, used SourceTree’s Create Patch menu option and got a diff file for this bug. I uploaded the file, and proceeded to the next. I repeated these steps for the other two bugs. (Conveniently, each of these bugs was in a separate chapter of the documentation).
> 
> OK, so now my SourceTree window includes multiple patches and branches. Geert has gone in to the respective bugs on Bugzilla and committed the patches (thanks, Geert!, and sorry about the errors!) into the main repository, which means my own patches and branches are superceded and superfluous. I don’t know how to get rid of them, and I don’t know how to update my local docs with the repository. With my current level of skill with Git, the only method I know to clean this up is to nuke it all again and start over, which I am reasonably sure is The Stupidest Way Possible.

Have you read http://git-scm.com/documentation? It’s not the manpage. It’s a well-written book that will help you understand how git works and how to use it effectively.

> 
> On to actual questions:

For the following I’m using “maint” as the public branch because that’s where we’re doing all of the documentation changes for now. There may be times where you’ll use “master” instead.
> 
> How do I tell my local copy to sync with the newer version online?

Check out maint by control-clicking on it in the branches list and selecting “Checkout foo” from the context menu where foo is the branch name. Click on the “Pull” button in the toolbar. If you’ve kept all of your changes in separate branches then you can just click “OK”, but if you have local commits on maint check the “rebase” first. But see below in “Should my patches be committed? (Or should I?)”. Since you didn’t actually commit anything, you can just reset your repo (Repository>Reset or shift-cmd-R, select Discard File Changes in the toolbar, check all files, click the Discard all Changes button) and then check out maint and delete each branch by control-clicking on it in the sidebar and selecting “Delete foo” from the context menu.

> 
> How do I tell my local copy that my changes went into the main repository and no longer need to live locally?
There are two ways, rebase the branch onto maint which would normally make it go away because maint will already have the commit or just force-delete the branch unmerged. In this particular case rebasing will have conflicts because Geert had to make some changes first. However, it looks like you made the patches by just diffing the changes rather than making commits and formatting them into patches. More on that below.

To rebase in SourceTree, check out each branch and then control-click on maint then select “Rebase current changes onto maint”.

SourceTree won’t let you force-delete a branch, so go to Terminal, cd to the repo directory, and do
  git branch -D foo
where foo is the branch name.

> Am I supposed to check something out? (besides passersby)

“Check out” is gittish for changing your working directory to what is in the repo for a particular commit. Each branch is actually just a pointer to the commit at the head of a series, so when you “checkout maint” or “checkout master” you’re setting your working directory to that commit. I explained how in SourceTree above, the command line way is 
  git checkout foo

> 
> Should my patches be committed? (or should I?)

You should have made commits and then made patches out of them. If you don’t commit your changes then making branches to work in doesn’t actually do anything, and switching branches may wipe out your changes if they conflict with what’s in the branch. In this case you were switching between branches pointed at the same commit (maint’s HEAD) so nothing happened.

When you make a commit you tag it with your name and write up a short description of the change, saving the developer who merges it into maint the trouble. You can also break up a complicated change into several pieces and have the ability to undo and redo those pieces until you’re happy with the result.

Once you have the commit you create patches from it (or them) by highlighting the commit and selecting “Create a patch…” from the context menu or using
  git format-patch
from the command line.

Note that SourceTree will make a single patch out of several commits while format-patch won’t, but I don’t know offhand what SourceTree does with the commit messages in that case.

As I said earlier, your working directory points at a commit and a branch points to the head of a series of commits. No commits, no branches. 

> 
> Would all of this be easier if I dropped SourceTree altogether and put together a dummy’s list of commandline commands that will walk me through this process?

You don’t have to dump Sourcetree to do some things in a command line. I routinely do some things in SourceTree and others from the command line depending on which way seems easier to me at the moment.

> 
> During my last Git episode, I created my own github account and mirrored gnucash-docs, but I have no idea how to utilize this in a meaningful way.

Once you’ve created a branch and committed changes to it you can push that branch to Github and use Github to issue a pull request. That’s less work than writing up a bug report just to contribute a change; in the case of a multi-commit branch it’s a lot less work at both ends.

Regards,
John Ralls