Using Github

[wobbly]

So I have no idea how to use this thing, but with some basic instructions from Quirk I managed to get this:

https://github.com/MichaelCourtney/angband/tree/master

4 commits behind master

https://github.com/MichaelCourtney/angband/tree/coffeeband

4 commits behind master, 1 commit ahead.

So I have some questions:

How do I bring those new commits from Master into my fork?

How do I selectively bring changes across?

All the stats seem to be for Angband master. I think I already tried to push to Angband by accident, I'd like to be able to play with this without accidently disrupting or annoying V coders, how do I make sure it's going to my own branch?

What even do all the terms mean? (push, pull etc.) Surely theres a Glossary somewhere?

Github tried to push some "Hello World" tutorial gimmick at me. This is fine except for the bit that I'd rather read an instruction manual. They seem to have deliberately put this up front & hidden away any manual. I mean perhaps it's useful? I'd rather look through a manual. Having this kind of gimmick shoved hard down your throat actually bugs me to the point I don't want to use it, good or not. I will in the end if it's actually worth it though.

[fph]

Quick intro: `git branch` will tell you which branch you are in. Note that there is a 'master' branch in your cloned repository as well. `angband:master` should be the official version.
If you are using the command line, `git merge angband:master`, given from inside your branch, should bring you up to date. Pray to the old gods and the new that there are no merge conflicts, or you are up for a tedious job of reviewing conflicting changes. If you haven't configured a graphical merge tool, it will be done by inserting markers in the files such as

<<<<<<<<<<<
version A
===========
version B
>>>>>>>>>>>

`git cherry-pick` allows you to selectively bring changes across.

`git help command-name`, for instance `git help pull` will give you some documentation, in the style of man pages. A tutorial does help, even if you only skim through it. `pull` means "bring changes in from a remote source", `push` means "export your changes to a remote source (not necessarily the official angband version, it may also mean your working copy on github).

[Quirk]

So, git has lots of documentation all over the web but it can be a bit detail heavy. I'll try to provide a brief overview on this push pull thing.

Git works off the idea you have a "repository" with the whole history of the source code on a machine, and lets you sync it with other machines and their repositories.

So if you go to your repository and type
git checkout master
You get your local master branch and all its known history which you can check with a git log or gitk or whatever.

If you want to get the latest changes from the repo you cloned from type
git pull
and it will pull in all the latest changes and update your branch. If you have your own commits on master it will merge them in.

So now you're up to date, you change some files, do a git add -u to add all your updates, then type git commit and write a comment. If vim worries you you can also type git commit -m "my comment" and write a short command line comment.

Then to upload your commit back to master you type git push.

If you have your own branch it's the same process to update it with github except your first push may need a set-upstream flag to tell git to create the branch in the other repo - if you need to do this git will tell you and show you the syntax.

Getting changes from master into your branch is a case of being in your branch (git checkout my branch); type git branch to check you're in the right branch then
git merge master

This merges changes from master into your current branch.

Selective changes are more tricky and may mean cherry picking commits.

Hope this helps.

[wobbly]

Ok so I have another question. Nick just changed part of a file that's different in mine but the part he changed is the same in mine. What happens if I try and pull it in? Will it try & change just that bit or the whole file.

[fph]

Yes, git can merge independent changes to different parts of the same file automatically (as long as the changed parts don't overlap, of course). That's one of the big advantages of version control systems.