Getting set up on github

FreeEMS topics that aren't specific to hardware development or firmware development.
User avatar
Fred
Moderator
Posts: 15431
Joined: Tue Jan 15, 2008 2:31 pm
Location: Home sweet home!
Contact:

Re: Getting set up on github

Post by Fred »

Re-reading this recently after linking it around a bit, I've noticed some missing info :

1)

The reason we need our own public repositories is to allow us to share our changes. You can not commit or push to my public repository, so you need a mechanism to get your stuff out there. In contrast to a typical SVN setup where everyone commits to a central repo, git moves the control to the person taking others changes in. You make your changes locally with no permissions etc required and then push them up for others to see and optionally ask the main person (aaron for tuner, me for firmware, seank for gcc, etc) to pull your changes down and merge them in. You've got more chance of them saying yes if your changes are clean, and just fast forward from the main persons latest public commit.

2)

In order to pull others stuff down to your local repo you need to add remotes for them. This is a configuration thing, see my config pasted below :

Code: Select all

# Potential FreeEMS Contributors:
#
# This is my .git/config file!
#
# It is included here for several reasons:
#
# 1) So that I can easily update it on different machines that I use.
# 2) So that you can learn from it and setup your remotes as required.
#
# Further help is available here: http://forum.diyefi.org/viewtopic.php?f=41&t=547
#
# Note: downstreams of this repo should add rebase = true to their master branch config
#
# More information is available here: http://forum.diyefi.org/viewtopic.php?f=41&t=1103
#
# Please talk to the lead developer of any repo which you plan to work on before doing so!

[core]
	repositoryformatversion = 0
	filemode = true

# My redundant remotes
[remote "origin"]
	url = git@github.com:fredcooke/freeems-vanilla.git
	fetch = +refs/heads/*:refs/remotes/origin/*
	push = refs/heads/master:refs/heads/master
[remote "raptor"]
	url = git:freeems-vanilla.git
	fetch = +refs/heads/*:refs/remotes/raptor/*
	push = refs/heads/*:refs/heads/*
[remote "freeems"]
	url = git@github.com:FreeEMS/freeems-vanilla.git
	fetch = +refs/heads/*:refs/remotes/freeems/*
	push = refs/heads/master:refs/heads/master
[remote "gitorious"]
	url = git@gitorious.org:freeems-vanilla/freeems-vanilla.git
	fetch = +refs/heads/*:refs/remotes/gitorious/*
	push = refs/heads/master:refs/heads/master
[remote "sourceforge"]
	url = ssh://fredcooke@freeems.git.sourceforge.net/gitroot/freeems/freeems-vanilla
	fetch = +refs/heads/*:refs/remotes/sourceforge/*
	push = refs/heads/master:refs/heads/master
[remote "repoorcz"]
	url = ssh://repo.or.cz/srv/git/freeems-vanilla.git
	fetch = +refs/heads/*:refs/remotes/repoorcz/*
	push = refs/heads/master:refs/heads/master

# Others forks
[remote "olli"]
	url = git://github.com/ohollmen/freeems-vanilla.git
	fetch = +refs/heads/*:refs/remotes/olli/*
[remote "seansrepo"]
        url = git://github.com/seank/freeems-vanilla.git
        fetch = +refs/heads/*:refs/remotes/seansrepo/*
[remote "philj"]
	url = git://github.com/johnsop1/freeems-vanilla.git
	fetch = +refs/heads/*:refs/remotes/johnsop1/*
[remote "mtxman"]
	url = git://github.com/djandruczyk/freeems-vanilla.git
	fetch = +refs/heads/*:refs/remotes/djandruczyk/*
[remote "marcos"]
	url = git://github.com/nitrousnrg/freeems-vanilla.git
	fetch = +refs/heads/*:refs/remotes/nitrousnrg/*
[remote "jaredh"]
	url = git://github.com/jharvey/freeems-vanilla.git
	fetch = +refs/heads/*:refs/remotes/jharvey/*
[remote "johnhowe"]
	url = git://github.com/johnhowe/freeems-vanilla.git
	fetch = +refs/heads/*:refs/remotes/johnhowe/*
[remote "simis"]
	url = git://github.com/simeonveldstra/freeems-vanilla.git
	fetch = +refs/heads/*:refs/remotes/simis/*

# Local inspection branches
[branch "master"]
	remote = origin
	merge = refs/heads/master
[branch "seank"]
	remote = seansrepo
	merge = refs/heads/master
I've simplified this to not show two private branches that I have connected to my origin for various reasons. You do not need branch config for normal private branches that you might create to work on ideas. Only if you want them connected to a remote location.

Note the remotes. The first batch are my public repos, they are all mirrors, I push to them as a set for redundancy. The next set is everyone else. I have no local branches pointing to these because it is not necessary the majority of the time. If I pull in a change and I'm unhappy with it, I can just reset --hard <my last revision> to remove the changes. If I have work in progress I can stash it and/or branch to keep the work separate from the incoming stuff until reviewed and merged/fast forward.

Code: Select all

git merge --ff-only otherbranch
which will merge otherbranch into whatever the current branch is with a fast forward action.

Note, when setting up the url section of a remote, any remote, you have to be careful with the format:

Code: Select all

git://github.com/username/projectname.git - this is for READ ONLY access.
git@github.com:username/projectname.git - this is for read/write access, known as "push access".
Additionally, the fetch section defines where to store what is obtained from that remote:

Code: Select all

fetch = +refs/heads/*:refs/remotes/usernameOfRemoteOwner/*
fetch = +refs/heads/*:refs/remotes/remotename/*
Either is acceptable, it just has to be unique. If it overlaps with another remote, then you'll get VERY weird and confusing behaviour.

I hope that helps and doesn't muddy the waters.

Fred.
Last edited by Fred on Fri Sep 23, 2011 7:19 pm, edited 4 times in total.
Reason: Update from experience.
DIYEFI.org - where Open Source means Open Source, and Free means Freedom
FreeEMS.org - the open source engine management system
FreeEMS dev diary and its comments thread and my turbo truck!
n00bs, do NOT PM or email tech questions! Use the forum!
The ever growing list of FreeEMS success stories!
User avatar
Fred
Moderator
Posts: 15431
Joined: Tue Jan 15, 2008 2:31 pm
Location: Home sweet home!
Contact:

Re: Getting set up on github

Post by Fred »

Firstly, some Git terminology disambiguation :
  • Branch - traditionally a branch was something off to one side of a trunk where the trunk could be referred to as head/mainline/master/main/trunk/etc. In Git, all strains of a project are a branch, including trunk/head/master/main/mainline/etc. Which branch you do your work on, and what it is called are entirely up to you and based upon the way in which you like to visualise the process.
  • Repository - a place, remote or local, that stores all branches of a project and potentially a checkout or working copy too. A local repository takes the form of a directory with a .git directory inside it. Usually you would have a checkout/working copy in the same directory as the .git directory. The check out is a set of files that represent the state of a particular branch with the possible addition of uncommitted work. A remote repository can not have a checkout and is purely a store of information about branches tags and commits.
  • Fork - traditionally this meant to take a project and work on it with a different purpose or goal and diverge from the originators work. In github terms, it could be like that, but it's much more likely that you'll want to get your work put back into the thing you forked from. Thus just consider it as a public copy that you retain control of independently of anyone else and a mechanism that facilitates others accessing your work in a convenient way.
There can be some overlap of these terms, however I will try to keep it aligned with the above.

Steps required to assist another user "Bob" with a project on github :
  1. Fork the other users repository on github
  2. Clone your fork locally from github (not the original users fork)
  3. Create a new branch with a name suitable for the other users work "bobs" (no need to do a checkout)
  4. Configure a named remote in your local repository pointing at the users fork "bob"
  5. Point the branch "bobs" to the other users fork by configuring it to use the named remote "bob"
  6. Work on your local branch "master" (the default branch) committing your changes as it makes sense to
  7. When done working and committing, push your changes to your fork on github
  8. Notify the other user to pull from your fork - pull request, email, forum post, private message, chat, phone call, telegram, paper cups with string, etc - it doesn't matter
  9. The other user, "Bob", hopefully, then pulls from your fork (to his local branch that points to your fork)...
  10. Examines your changes, hopefully accepting them, and merging them into his local master branch...
  11. Pushes the combined work back to his fork on github!
  12. Checkout your branch "bobs" and pull down the combined work from "Bob's" fork on github
  13. Examine his merge efforts and commit hashes etc and confirm that it is A OK
  14. Checkout your branch "master" and merge in the material from the branch "bobs"
  15. You're up to date, push the combined work up to your fork and carry on working!!!
The above assumes that you do not already have a fork of the same project from some third user. If you do, no need to fork. You can just create a another branch, reset it to the first common commit between the other two users and pull down down Bob's work.

There are some assumptions above. One of them is that you stopped working while Bob merged in your stuff. There may be others.

Writing this post took a long time as I corrected and re-corrected my language to be consistent and more clear.

I hope this helps further. The next post will be a practical example of the above.

Fred.
DIYEFI.org - where Open Source means Open Source, and Free means Freedom
FreeEMS.org - the open source engine management system
FreeEMS dev diary and its comments thread and my turbo truck!
n00bs, do NOT PM or email tech questions! Use the forum!
The ever growing list of FreeEMS success stories!
User avatar
Fred
Moderator
Posts: 15431
Joined: Tue Jan 15, 2008 2:31 pm
Location: Home sweet home!
Contact:

Re: Getting set up on github

Post by Fred »

Now for the commands and output.
  1. Fork the other users repository on github - http://help.github.com/forking/
    Image
  2. Clone your fork locally from github (not the original users fork)
  3. Create a new branch with a name suitable for the other users work "tortures" (no need to do a checkout)
  4. Configure a named remote in your local repository pointing at the users fork "torture"
  5. Point the branch "tortures" to the other users fork by configuring it to use the named remote "torture"
    Image
  6. Work on your local branch "master" (the default branch) committing your changes as it makes sense to
  7. When done working and committing, push your changes to your fork on github
    Image
  8. Notify the other user to pull from your fork - pull request, email, forum post, private message, chat, phone call, telegram, paper cups with string, etc - it doesn't matter
    Image
  9. The other user, "Torture", hopefully, then pulls from your fork (to his local branch that points to your fork)...
  10. Examines your changes, hopefully accepting them, and merging them into his local master branch...
  11. Pushes the combined work back to his fork on github!
    Image
  12. Checkout your branch "tortures" and pull down the combined work from "Torture's" fork on github
  13. Examine his merge efforts and commit hashes etc and confirm that it is A OK
  14. Checkout your branch "master" and merge in the material from the branch "tortures"
    Image
  15. You're up to date, push the combined work up to your fork and carry on working!!!
    Image
I've done things slightly differently to what is listed, but with the same exact result. I kinda faked the above a bit as well, but it should be hard to tell unless you go checking hashes etc. It is important to realise that there are many ways to skin the above cat. This is just a nice simple one.

Thanks to torture for unknowingly allowing me to abuse a fork of his repository for the purposes of this post :-)

Hopefully this helps a few people.

Fred.
DIYEFI.org - where Open Source means Open Source, and Free means Freedom
FreeEMS.org - the open source engine management system
FreeEMS dev diary and its comments thread and my turbo truck!
n00bs, do NOT PM or email tech questions! Use the forum!
The ever growing list of FreeEMS success stories!
MotoFab
1N4001 - Signed up
Posts: 307
Joined: Thu May 29, 2008 1:23 am
Location: Long Beach CA

Re: Getting set up on github

Post by MotoFab »

THANKS for all that great information Fred!

Here are some Git tip sheets that I found useful:
GitHub Cheat Sheet: http://github.com/guides/git-cheat-sheet
Changing Git Commit Messages and History: http://schacon.github.com/history.html
Git short form: https://git.wiki.kernel.org/index.php/GitCheatSheet
More Git documentation links: https://git.wiki.kernel.org/index.php/GitDocumentation

* * * * *
Git GUI on Windows:
Over the last few days I've sorted out MSysGit, and set up a test repo on GitHub. I'm using MSysGit which is the runs-on-windows version of Git. It runs great on XP, and integrates nicely into the windows explorer context menu. The linux version of Git includes the nice 'git-gui' user interface too.

Precompiled MSysGit download link on either of these pages:
http://code.google.com/p/msysgit/
http://git-scm.com/download
The MSysGit package installs both Git and MSYS.

* * * * *
It isn't needed, but I also installed TortiseGit (note: TortiseGit only works with MSysGit, and not with Cygwin running) TortiseGit is another flavor of gui for Git. It has more windows exlplorer context menu items. It works fine too, but I haven't used it much yet.
Available here: http://code.google.com/p/tortoisegit/

* * * * *
I had a ton of setup problems regarding setting up SSH with PuTTY, Pageant, PLink, and/or OpenSSH. Two words, Environment Variable. Jeez!

Anyway, Git works in windows!

Edit: Fred found that TortiseGit does work with Cygwin.
Last edited by MotoFab on Thu May 06, 2010 7:51 pm, edited 1 time in total.
User avatar
Fred
Moderator
Posts: 15431
Joined: Tue Jan 15, 2008 2:31 pm
Location: Home sweet home!
Contact:

Re: Getting set up on github

Post by Fred »

MotoFab wrote:THANKS for all that great information Fred!
Most welcome!
Changing Git Commit Messages and History: http://schacon.github.com/history.html
This should almost always ONLY be done in private (before you push and only in un-pushed history of your own) - just to be clear :-)
Anyway, Git works in windows!
Sure does, I was using it in London on winblows quite a bit. It's significantly slower than on Linux, though. (But still faster than other version control systems)

Fred.
DIYEFI.org - where Open Source means Open Source, and Free means Freedom
FreeEMS.org - the open source engine management system
FreeEMS dev diary and its comments thread and my turbo truck!
n00bs, do NOT PM or email tech questions! Use the forum!
The ever growing list of FreeEMS success stories!
User avatar
jharvey
1N4001 - Signed up
Posts: 1607
Joined: Tue Jun 10, 2008 5:17 pm

Re: Getting set up on github

Post by jharvey »

I thought I'd post about using TortiseGIT on windows. Right now I cloned a couple of the freeems git repos, and when Fred indicates he made a change, I'll pull the repo. Here are some pictures of the steps after I installed TortiseGIT. If you plan to make and share your own changes, it's best to do a fork via web page, as described in Freds how-to.

First get the link you need to do the clone. Note this link specifies it's read only. So I don't have to worry about buggering the web copy.

Image

The browse to the folder where you plan to have this copy.

Image

Now paste in the link you copied in the first step.

Image

This is how it looks while it's doing the check out.

Image

It's fairly quick, so you might not see the above picture for very long. You will see this dialog if all goes well.

Image

After you hit "close", you can browse the folder and make a day of it. When there is a change, or you want to confirm your copy is the same as the dev copy, simply do a pull.

Image

There are several other features that are interesting to play with. Click around and see what happens. The TortiseGIT gui makes some pretty graphs to show the history and how the code evolved.

So these days, GIT can be used by mere mortals like myself.
MotoFab
1N4001 - Signed up
Posts: 307
Joined: Thu May 29, 2008 1:23 am
Location: Long Beach CA

Re: Getting set up on github

Post by MotoFab »

jharvey wrote:There are several other features that are interesting to play with. Click around and see what happens. The TortiseGIT gui makes some pretty graphs to show the history and how the code evolved.

So these days, GIT can be used by mere mortals like myself.
Nice writeup on the cloning process using TortiseGIT!

I've been experimenting with some of the TG features too. The 'Create' and 'Apply' serial patch functions make that process easy. I can't imagine trying to do that using command lines in a terminal.
User avatar
jharvey
1N4001 - Signed up
Posts: 1607
Joined: Tue Jun 10, 2008 5:17 pm

Re: Getting set up on github

Post by jharvey »

I'm moving this from http://www.diyefi.org/forum/viewtopic.p ... &start=180 to here to keep this a bit more on track with the thread subject.

I had forked Fred's vanilla back in 2008. I was unable to figure out how to get my github forked copy to update to the newest code that Fred posted. So in the above pictures of TortiseGIT, I cloned Freds copy in a separate directory from my original. That allowed me to get Freds latest changes by continuously pulling from his copy. However, that present problems because that's his repo, not mine, and when I want to post potential changes to be merged with his repo, he can't see or access my repo, and I can't post it to his. It appears the best way to do this is with the fork option, but I don't know how to correctly operate that feature at this time.

I found this guide http://github.com/guides/keeping-a-git- ... orked-repo The steps I'm trying to attempt with TortiseGIT will be slightly different from this guide.

Under the TortiseGIT --> settings --> remote, I'm including both mine and Fred's repos. Then I'm pulling a local copy of Freds repo, then I'm attempting to push to my public github repo. Once it's there, then I can send a pull request to Fred. This should go well once I figure out how to push mine up to the my github account. I'm having a bit of trouble with getting the RW communications to work. I'm not currently sure why it flops and it' time for bed.

If anyone can push with TortiseGIT to a github repo, please post some pictures, or something. I'm a bit lost at the moment. I can get the git read only access to work, but I can't push because of communication failures.
User avatar
sry_not4sale
LQFP144 - On Top Of The Game
Posts: 568
Joined: Mon Mar 31, 2008 12:47 am
Location: New Zealand, land of the long white burnout
Contact:

Re: Getting set up on github

Post by sry_not4sale »

Have you checked the github docs?

I would have thought most write failures would be from not having your ssh keys set up correctly.

Hope that helps,
Aaron
Owner / Builder: 1983 Mazda Cosmo 12at (1200cc 2-rotor turbo) coupe [SPASTK]
165hp @ 6psi standard - fastest production car in japan Oct 82
User avatar
jharvey
1N4001 - Signed up
Posts: 1607
Joined: Tue Jun 10, 2008 5:17 pm

Re: Getting set up on github

Post by jharvey »

Well there we go. Yup it was public and private key issues. Basically putty key's are formated differently than how the github docs tell you to generate your keys. I noticed that when I opened my github public key it looked like this.

Code: Select all

ssh-
rsaAAAB3NzaC1yc2EAAAABJQAAAIB/9glF2DNFo/gz+eibxUH/agLph2womwekEi0BKPtpLI6ATtm+riOeCIbibslIWLSq+UepcnNlB6pnthr4abPpWMUKGuk2PYl4pN+eET4hYOt4YrRTVpRoIcsF0tIVFX5ckhcfr3xUtAQRJFHXdBXMu3cZE+kalpTBa1DjmjOAlQ==
However the key I generated on one of my Linux boxes didn't look quite the same. So I made my public key look like this.

Code: Select all

ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIB/9glF2DNFo/gz+eibxUH/agLph2womwekEi0BKPtpLI6ATtm+riOeCIbibslIWLSq+UepcnNlB6pnthr4abPpWMUKGuk2PYl4pN+eET4hYOt4YrRTVpRoIcsF0tIVFX5ckhcfr3xUtAQRJFHXdBXMu3cZE+kalpTBa1DjmjOAlQ==
Now all is good. The key to make it look like that when I opened the edit page was to add a space to the end of ssh-rsa. With out that space, it will automatically wrap the lines. With out that space, you can edit the key entry page and make it look that way, but when you close then re-open the key, you'll notice it's been formated differently than how you saved it. Add the space, and you'll be all set.

Also the putty generated key is much different than that key file. It had comments and other tags included that I had to strip out to make a minimal version. The putty key also doesn't include the ssh-rsa part. I had to remember that's the method I used.

Now I guess I can try a push to get my mild changes available for Fred to look over and perhaps merge.
Post Reply