Fun with Git

[John Ralls]

> On Feb 10, 2015, at 2:52 AM, Geert Janssens <geert.gnucash at kobaltwit.be> wrote:
> 
> On Tuesday 10 February 2015 09:17:29 Colin Law wrote:
>> On 10 February 2015 at 05:36, David T. <sunfish62 at yahoo.com> wrote:
>>> Thanks for the leads. I have been reading, but the descriptions of
>>> how it’s supposed to work aren’t matching my experience.
>>> Specifically, the manuals all talk about pushing changes onto the
>>> repository—but I don’t have push capabilities with the gnucash-docs
>>> repository. Thus, when I get errors about needing to push my
>>> changes, I don’t know how to get out of the situation.
> 
> I'm happy to hear you're making progress in your documentation adventure.
> 
> Push access to the main repositories is currently limited to a small set of core developers. So 
> it's normal you get an error when you try to push your changes.
> 
>>> My realm is
>>> “3 ahead”, and I cannot figure out how to proceed. I followed the
>>> prompts that said to stash my changes, but now I can’t locate the
>>> changes I want to submit for bug 693156. I see the changes in the
>>> files on my hard drive, so I know they are there, but for the life
>>> of me, I can’t figure out how to get git to get them.
> 
> If your local branch is 3 commits ahead of origin (the upstream repository), that means you 
> have successfully created 3 commits with the combination of git add/git commit.
> 
> To review what is actually in these commits, I usually fire up "gitk" from within my local 
> repository directory. That allows me to visually inspect which changes I made and whether they 
> are in a shape I want to send upstream.
> 
> This may be worthwhile for you as well since these are your first steps and perhaps you did 
> things you didn't intend.
> 
> If you are satisfied with the way the commits are, you can execute
> 
> git format-patch <parent-branch>
> 
> <parent-branch is the branch you originally started off from which I can't deduce from your 
> mails. Most likely it should be origin/master in your case.
> 
> This command will generate independent patch files, usually called 
> "000x-something" in the root of your local repository. These patch files can then be attached to 
> a bug report.
> 
> As for the stashed changes, Colin already explained how you can recall those. You can also 
> display an overview of stashed changes using
> git stash --list
> 
> In general stashing changes is only needed if you are in the middle of some work you don't 
> deem good enough yet to commit, but need to set aside quickly to work on something else first. 
> I wouldn't recommend it as the primary management mechanism in git.
> 
> You're better of creating lots of branches. For example one branch for each bug you are working 
> on. Unless the work on two bugs has big overlaps that is affecting the same lines in the same 
> files. In that case you are probably better of doing those changes on the same branch.
> 
> One more potential pitfall: create your new branches when you have checked out master, not 
> another branch.
> 
> Perhaps you can post a screenshot of the gitk window - that would allow me to give you much 
> more precise guidance.

David,

One more thing: Make a Github account and fork Gnucash/gnucash-docs into it. That will give you a remote to push to and generate pull requests from. That will save you having to make patches and upload them to BZ and will be easier to review.

You'll use
git remote rename origin upstream
git remote add origin git at github:youraccount/gnucash-docs.git
to create the new remote. After the initial fork you'll need to periodically
git checkout master
git pull --rebase upstream master
git checkout maint
git pull --rebase upstream maint
git push origin master maint
to keep your github repository in sync with the canonical one. You'll also push your change branches there.

Geert's advice to make lots of branches is really good. Git works amazingly well with branches, and branches provide a convenient point to make pull requests, so make at least a separate branch for each topic you're addressing and push each to Github. As soon as they're there we'll be able to look over your work and tell you if you're on the right track or if you need to change something, and we can do it line-by-line right in Github.

If you do all of your work in topic branches then you won't need to rebase your pulls from upstream.

Regards,
John Ralls