|
|
| (40 intermediate revisions by 5 users not shown) |
| Line 1: |
Line 1: |
| − | Developing on pioneer means using the version control tool 'git' and the [https://github.com/ github] website. git especially has a reputation for having a steep learning curve, so here we'll try to give you enough knowledge to be dangerous!
| + | Page moved to: |
| | + | https://dev.pioneerspacesim.net/contribute/git-and-github |
| | | | |
| − | == Prerequisites ==
| + | Any edits should be made there, i.e. can use github editor and edit inplace |
| − | | + | https://github.com/pioneerspacesim/pioneer-developer-docs/blob/master/contribute/git-and-github.md |
| − | A working installation of git, a GitHub account, and comfort with using the command line of your chosen operating system.
| |
| − | | |
| − | The GitHub sign-up page is [https://github.com/signup/free here]. Make a note of your user name as you'll need it to make your local pioneer repository.
| |
| − | | |
| − | On Linux, git is available in all distributions using the standard tools such as APT, yum or emerge. Since there is a wide range of file browsers and graphical environments, this tutorial limits itself to the command line interface.
| |
| − | | |
| − | On Windows you have two options, [http://msysgit.github.com/ Git for Windows] aka msysgit, or [http://windows.github.com/ Github for Windows] which is essentially msysgit but with some extra stuff bundled. Some of which is good ([https://github.com/dahlbyk/posh-git posh git]) and some of which is well, not (github's 'friendly' gui). Since both include the same command line tools and cross platform gui tools, either is fine for our purposes here. The github one may be more convenient to install.
| |
| − | | |
| − | On Mac OS X, git will have been installed with XCode as git is built into the XCode IDE. However, usage of git from from within an IDE isn't something I'm familiar with so isn't covered here. If you want to follow along with this document then if you elected to install the XCode command line tools, then the git commands below should work unaltered from a terminal window. If you didn't then you'll need to use <code>xcrun</code> to run the commands in terminal, either by adding <code>xcrun</code> in front of each of the commands or aliasing <code>git</code> and <code>gitk</code> to <code>xcrun git</code> and <code>xcrun gitk</code> in your <code>~/.profile</code>. Have a look at [http://www.cocoanetics.com/2012/07/you-dont-need-the-xcode-command-line-tools/ this guide] for details.
| |
| − | | |
| − | A clear and concrete introduction to git can be seen at this [https://rogerdudler.github.io/git-guide/ Git Guide]
| |
| − | | |
| − | == Creating your pioneer repositories ==
| |
| − | | |
| − | Git, as a version control system, stores all source files for Pioneer (or any other project you've chosen to manage with git) along with their histories in '''repositories''' (usually shortened to just 'repos'). These are areas of a computer's file system where has git has been told to track and manage changes to the files placed in them.
| |
| − | | |
| − | There are three different repositories that you mainly deal with when developing pioneer.
| |
| − | | |
| − | * The <code>upstream</code> repo. This is the main Pioneer repository stored on GitHub. This is read-only except to the core team (and even they don't do their development there).
| |
| − | * The <code>origin</code> repo. This is a public Pioneer repository personal to you, but stored on GitHub under your username, so other people can see the changes put into it. This is read-only to everyone except you.
| |
| − | * The <code>local</code> repo. This is your personal Pioneer repository on your computer, not accessible by anyone else.
| |
| − | | |
| − | Before you can start developing you need to setup both your Pioneer <code>origin</code> and <code>local</code> repositories.
| |
| − | | |
| − | === Your origin repository ===
| |
| − | | |
| − | Your <code>origin</code> repository you make on GitHub. To do that, make sure that you're logged in there and go to the main [https://github.com/pioneerspacesim/pioneer GitHub Pioneer page] in your web browser, and click the 'Fork' button at the top of that page:
| |
| − | [[File:ForkPioneer.png]]
| |
| − | | |
| − | | |
| − | GitHub will clank and whirr as it makes a copy of the main Pioneer repo under your username. Eventually it will finish, and you'll end up on page almost exactly like the main GitHub Pioneer page, but instead of being named <code>pioneerspacesim/pioneer</code> your copy is named <code><your github user name>/pioneer</code>.
| |
| − | | |
| − | Having made your <code>origin</code> repo, you're now ready to make your local one.
| |
| − | | |
| − | === Your local repository ===
| |
| − | | |
| − | You make your <code>local</code> repository by cloning a copy of your new <code>origin</code> repository to your local machine.
| |
| − | | |
| − | At the command line, navigate to where on your filesystem you want to put your local git repos. For instance on Linux I put mine in <code>~/repos</code> whilst on Windows I put them in <code>c:\develop\github-repos</code>. You can move the folder at a later time without breaking anything. Once you're there execute the following command replacing <code>your github username</code> with, well, your github username.
| |
| − | | |
| − | git clone git://github.com/your gituhub username/pioneer.git
| |
| − | | |
| − | Just like clicking Fork on the main Pioneer GitHub repo made a clone of it under your GitHub account, this makes a clone of that clone to your local machine. Expect this to take some time, just like before, as it copies all the files and the complete history of the project to your filesystem, only now it's sucking the data from GitHub to your machine, rather than copying things around within GitHub's data centre (so it will probably take even longer; however, a modern coputer does it on the order of minutes).
| |
| − | | |
| − | Eventually this operation will complete, and you'll have a shiny new directory named <code>pioneer</code> which git -- with a little encouragement -- will manage for you, your <code>local</code> repo.
| |
| − | | |
| − | We're almost done with repository setup, but there is one more thing we need to attend to. When you did <code>git clone</code>, it automatically set <code>origin</code> to point to your Pioneer repository on GitHub. However it didn't set <code>upstream</code> to point the main Pioneer Repository. We'll need to do that manually.
| |
| − | | |
| − | We must to be inside the repository to do this, in fact all the git commands from now on, you need to be inside a repository to execute any of the git commands shown. So enter the pioneer repository directory, before doing:
| |
| − | | |
| − | git remote add upstream git://github.com/pioneerspacesim/pioneer.git
| |
| − | | |
| − | ...to define <code>upstream</code> as the main Pioneer repository. You'll notice you defined <code>upstream</code> as a <code>remote</code>, <code>origin</code> is also defined as a <code>remote</code>. We'll explain more about remotes later on.
| |
| − | | |
| − | You can now view the result of our commands, i.e. see how we link the <code>origin</code> to your git repo, and upstream to the central pioneer repository.
| |
| − | | |
| − | git remote -v
| |
| − | | |
| − | == Basic operations ==
| |
| − | | |
| − | At this point you might want to consider searching for tutorials. There are many good ones on git out there. If you're familiar with svn look [http://git.or.cz/course/svn.html here], and [http://marklodato.github.io/visual-git-guide/index-en.html this] is a nice visual representation of different commands, which might be helpful. Basic git tutorials on youtube: [https://www.youtube.com/watch?v=vaNGbk6HN9Y part 0], [https://www.youtube.com/watch?v=DQUcmNO4diQ part 1].
| |
| − | | |
| − | | |
| − | git branch
| |
| − | | |
| − | git status
| |
| − | | |
| − | git checkout <branch-name>
| |
| − | | |
| − | git branch <branch-name> ; git checkout <branch-name>
| |
| − | git checkout -b <branch-name>
| |
| − | | |
| − | gitk
| |
| − | | |
| − | git add -A ; git commit
| |
| − | git commit -a
| |
| − | | |
| − | git push origin <branch name>
| |
| − | | |
| − | == Updating your branches ==
| |
| − | | |
| − | Makes no changes on your local copy, but reads in what changes there are upstream. A safe command.
| |
| − | git fetch upstream
| |
| − | | |
| − | git merge
| |
| − | | |
| − | git pull --ff-only upstream master
| |
| − | | |
| − | This merges your master branch into your current one
| |
| − | git merge master
| |
| − | | |
| − | To discard all changes on your branch "my-branch" and resync them with the upstream version you have in your hithub
| |
| − | git reset --hard origin/my-branch
| |
| − | | |
| − | == Resolving Conflicts ==
| |
| − | | |
| − | == Making a pull request ==
| |
| − | | |
| − | == Getting code from other branches ==
| |
| − |
| |
| − | git checkout <branch-name> -- <file-name>
| |
| − | | |
| − | git merge <branch-name>
| |
| − | | |
| − | == Getting other developer's branches ==
| |
| − | | |
| − | git remote
| |
| − | | |
| − | git remote add <remote> <url>
| |
| − | | |
| − | git remote update
| |
| − | | |
| − | git checkout -b <branch-name> --track <remote>/<remote-branch-name
| |
| − | | |
| − | == Keeping things tidy ==
| |
| − | | |
| − | git branch -d <branch-name>
| |
| − | | |
| − | git branch -D <branch-name>
| |
| − | | |
| − | git push origin :<branch-name>
| |
| − | | |
| − | git clean -n
| |
| − | | |
| − | git clean -f
| |
| − | | |
| − | == Reviewing a pull request ==
| |
| − | | |
| − | == Rebasing and cherry picking ==
| |
| − | | |
| − | '''Warning''': Rebasing and cherry picking, although sometimes useful, can cause problems for other developers if you use them on commits that have already been published to github. Be careful and give sufficient warnings if you find you needing to use them in that situation.
| |
| − | | |
| − | git cherry-pick <commit>
| |
| − | | |
| − | gitk
| |
| − | | |
| − | git rebase <branch-name>
| |
| − | | |
| − | git rebase -i <branch-name>
| |
| − | | |
| − | == Pushing to upstream Pioneer Master ==
| |
| − | For those with push access to https://github.com/pioneerspacesim/pioneer this is one way to push code to master. First make sure you have a resonable setup:
| |
| − | | |
| − | git remote -v
| |
| − | origin https://github.com/myusername/pioneer.git (fetch)
| |
| − | origin https://github.com/myusername/pioneer.git (push)
| |
| − | upstream https://github.com/pioneerspacesim/pioneer.git (fetch)
| |
| − | upstream https://github.com/pioneerspacesim/pioneer.git (push)
| |
| − | | |
| − | | |
| − | git checkout master
| |
| − | git merge --no-commit --no-ff feature_branch
| |
| − | | |
| − | Document changes to Changelog.txt, then add it, from the pioneer root folder:
| |
| − | | |
| − | git add Changelog.txt
| |
| − | git commit
| |
| − | | |
| − | This has now included the Changelog edit into the merge commit. Now do a dry run:
| |
| − | | |
| − | git push upstream master --dry-run
| |
| − | | |
| − | Check that the right commits will be pushed with
| |
| − | | |
| − | git log
| |
| − | | |
| − | And let us do it for real this time:
| |
| − | | |
| − | git push upstream master
| |
| − | | |
| − | | |
| − | Please note: NEVER do a force push to pioneer master!
| |
