Win GitHub for N00bs
#1
Lets get this out of the way, GITHub is awesome but the learning curve is crazy hard.

Image Image

Here's a little guide to starting off from the perspective of a n00b while attempting to put it in plain English.

I'm assuming you have signed up for github and are working on Windows with TortoiseGIT installed. Other platforms and Git tools should work in a similar way.


Cloning a Repository
Copying an existing project from the GITHub website and all its code to your local computer.
This is usually used when you want to test a one time copy of a project on your local computer without making any changes in the future


1) Create a folder on your computer for the projects to be stored in. I chose C:\GITProjects
2) Right click on the folder GITProjects >> Clone a repository
3) Lets take the example of the full XBMC source code so we type into the https://github.com/xbmc/xbmc URL field. And C:\GitProjects\XBMC into the Directory field.

Image



Forking a Repository
Making a copy of an existing project on the GITHub website and Downloading it to your local computer.
This allows you to upload commits and pull requests in the future without effecting the original repository


1) Create a folder on your computer for the projects to be stored in. I chose C:\GITProjects
2) Go to the GitHub website and find the project you want to fork. Then click on the Fork button in the top right corner. It should only take a few seconds and then the project will show in your own GitHub area.

Image

3) Right click on the folder GITProjects >> Clone a repository
4) Now simply enter the URL of the new fork you have created and a local folder to put it in.




Creating a new Project
Uploading an entire new project from your local computer to GitHub

1) Got to github.com and create a new repository
Image

2) Go to your local computer and create a new directory for your project. For example c:\GITprojects\MyProject. Make sure it is empty for now.

3) Copy the URL of the repository you created into the clipboard memory

4) Right click on the root "Gitprojects" folder >> Clone a repository. Your URL should be auto completed and so should the source. Click OK and wait for it to set the repository up.

5) Now copy any project source code you have written into the "MyProject" folder.

6) Right click on "MyProject" >> Gti Commit -> Master. Type in something like "initial commit" in the message box. Now click on the "ALL" button to select all your files to upload.

7) After the files are uploaded, click the push button to finalize the operation. That's it, all your files should now be stored in the on-line GitHub repository Smile


Committing a piece of code to your own repository
Commiting a small piece of code to your own project on GitHub

1) Copy or edit your code in the c:\Github\Project1 folder

2) Go back to the root of c:\Github and right click on the "Project1" folder -> Git Commit -> "Master"

3) In the box write a commit message and make sure you have selected the files that are added or changed with the tick box.

4) Once the files have been commited, hit the PUSH button to upload them to the GitHub website.

5) You can now check the files are uploaded by browsing to the github website and specific repository.



Creating a pull request
Packaging up a new feature or code change for others to review and comment on

1) Navigate to the github website and your personal repository (usually this will be a fork of another repository)

2) Commit and push any changes to your personal version of the code.

3) Once you have uploaded your changes you can go to the repository and click "Pull Request"

4) Add a name for the PR and make any comments. Github should automatically find and changes in the file.

5) Once your pull request is complete, people will be able to comment on it and merge it.


Squashing commits into one
Squashing a number of commits down to a single commit so its easy to review and keep track of

1) Assuming you have a couple of commits, right click on the repository >> tortoise >> show log
2) Select the commits right click >> combine to one commit
3) Right click on the repository >> tortoise >> Push.
4) Check the box that says force overwrite existing branch


Resetting your local master
Resetting your local master back to a remote master

1) Right click on the repository >> Switch to master
2) Right click on the repository >> Show log
3) Change to the XBMC remote master repository in the top left hand corner
4) Right click on the latest commit >> Reset
5) Choose hard reset (warning this will delete any local changes)


Amend to last Commit
If you make a commit then have to add something to it
1) Right click on the repository >> Commit (this will be the 2nd commit)
2) Check tickbox that says "Ammend to last commit"
3) Check tickbox that says "Force push" to your own repository

Testing someone elses pull request
Pulling down a set of patches that you can apply to your local repository and test out

coming soon...
Reply
#2
Submitting a PR to Kodi Repository
Making a copy of the Kodi code, branching your own version of that code, submitting changes and creating a "Pull Request"

1) Create a folder on your computer for the projects to be stored in. I chose C:\Code
2) Go to the GitHub website and find the XBMC/Kodi project. Then click on the Fork button in the top right corner. It should only take a few seconds and then the project will show in your own GitHub area.
3) Copy and paste the new URL, in my case its https://github.com/zag2me/xbmc
4) Right Click on the C:\Code folder and click "Clone Repository"
5) Right Click on the newly created C:\Code\XBMC folder and TortoiseGIT menu item >> Create Branch
6) Call the branch the name of the feature you are creating. Make sure you click the "Switch to Branch" check box. Also make sure its based on the HEAD (Master ) branch
Image

8) Make the changes to the code you want. Be careful to follow the coding guidelines and syntax's used in the rest of the code.
9) Once all your changes have been made, right click on the "C:\Code\XBMC folder" and select >> Git Commit
10) Make sure the commit message is descriptive. We usually use the part of code in brackets then a description of the code
11) Press OK, then Push button then OK again. You will probably have to enter your password here as you are uploading the code to your own branch on github.
12) Go to the Github website and find your XBMC branch. Click the big green button "Create Pull Request".
13) Make sure the base fork is xbmc/xbmc and the your repo and the correct branch
14) Write a nice description and click Create Pull Request.

Congratulations you are now a Kodi Developer! Keep calm when discussing the pull request with experience dev's. They will give advice, but deal with hundreds of pull requests a month so will need convincing its the best code before officially merging.
Reply
#3
*Reserved*
Reply
#4
I'm on a Mac but this will still be useful.. i find even even the native Githug app confusing enough Tongue
Reply
#5
Looking forward for the coming bits since I haven't really learned Github and what you can do with it and how to do it.

A suggestion:
Clarification on how to download or fork the latest stable vs. nightly.

Some questions that could be answered here as a faq:
Do I need an Github account? (What can you do and not do without an account)
Can I have a local Repository on my computer/network?
Reply
#6
Updated original post with:

"Creating a new Project"
Reply
#7
Hey zag, if you need a hand with this I can help.
Reply
#8
Thanks, and yes please write any guides down and I will update the 1st post.
Reply
#9
Updated the guide to include

"How to commit individual files or code edits"
Reply
#10
@zag

This is a good effort on documenting github how-to however a more complete guide which you can draw on for instructions for inclusion on your posts can be found here http://forum.xda-developers.com/showthre...p=31304826

I never had used github until a few months back and cant code anything to save my life, however it wasn't difficult at all because github most stuff you can do over browser, rest google did the trick (like rebase/squash/push

Hope you find that xda thread helpful

uNi
Reply
#11
- Updated with how to make a Pull Request.
Reply
#12
Although I offered to help, I later noticed you are using tortoisegit which I have no intention of using.

I think github is crazy easy if you know how git works.
I also think git should always be used from a command line.

This is one of the best manuals for git available and can even be downloaded as PDF for free (which is the preferred cost for anything imho):
http://git-scm.com/documentation
Reply
#13
I so disagree on using got from command line.
I use SmartGit and have never ever needed to use any command line
Read/follow the forum rules.
For troubleshooting and bug reporting, read this first
Interested in seeing some YouTube videos about Kodi? Go here and subscribe
Reply
#14
I'm sure the command line is better and more powerful once you learn, but most people will want to start with some kind of GUI tool.

Coming from SVN and using tortoise it was the obvious choice, but interesting to know their are other tools out there.
Reply
#15
Their Windows gui is also very nice http://windows.github.com/ , though you can't do everything that the command line supports.
Reply

Logout Mark Read Team Forum Stats Members Help
GitHub for N00bs1