I've been reading the thread Mi git usage (my thanks to Cjkjvfnby, adrian_broher, wheals...). I'm trying to understand it all while compiling all the instructions for simple (mechanical?) but safe command-line git usage (and web github usage when necessary).
Also, if this isn't an appropriate place for this post/thread, don't hesitate to move it to wherever is better than here.
Edit: I've found this very helpful article at github on git workflow. Maybe it renders useless this thread
I'll incorporate all the info and correct mistakes when I get the time.
One thing I've already seen is that the instructions I gathered from the forum were aimed at the owners of the upstream repo and not for contributors working on their fork.
[[Work in progress]]
First time you use git:
First of all, if you don't have one, you need to sign up into https://github.com/ to create a user.
And then you'll have to do some things once:
Create in github a fork (an online copy) of the original FO repository:
- Log in into your github account.
- Open the URL of the FO project: https://github.com/freeorion/freeorion.
- Click on the fork button.
You will own this online repo. You'll be able to work on it, make changes and request the owners of the original repo to (review and) pull (PR: pull request) them from your repo to incorporate them into the original FO repo.
Create in your machine a local copy of your FreeOrion fork:
Code: Select all
~$ git clone <URL of your FO github fork>
Add the original FO repo as a remote to your locak fork:
Explained in help.github.com/articles/configuring-a-remote-for-a-fork/
Code: Select all
~$ git remote -v # lists your current remotes (one for push, one for pull, both pointed at your online fork)
~$ git remote add upstream https://github.com/freeorion/freeorion.git
~$ git remote -v # verify the new upstream repository (one for fetch and one for push, both pointed at original FO repo)
- Set up some fancy color ui stuff (I assume):
Code: Select all
~$ git config --global color.ui auto
Code: Select all
~$ git config --global core.editor "<path_to_editor_you_like/command_line>"
Code: Select all
~$ git config branch.master.rebase true
Making changes in your local copy:
Now you can edit files in your local FO folder (that is a copy of your online FO fork) to make your contributions.
Eventually, you'll want to add your changes to the upstream repo. For this you will group them in a "package" with a common descriptor message. So it's better if you focus on changes related to the same objective and follow this workflow: make changes, compile if needed, test, rinse and repeat until you get what you were looking for (a bug patch, a new mechanic, balance adjustments...). Then you'll push those changes with its informative message to your online fork and then you'll be able to do a PR from your fork to the upstream repo (any given branch of it).
Before you push those changes you have update your repo with the upstream repo to make sure there are no conflicts.
Keep your master up to date with upstream master:
Explained rather well in this help.github.com/articles/syncing-a-fork/
Code: Select all
~$ git fetch upstream # Fetch the branches and their respective commits from the upstream repository.
~$ git checkout master
~$ git merge upstream/master # Merge the changes from upstream/master into your local master branch.
Keep your online fork up to date with the original master:
Code: Select all
~$ git push
Pushing those changes into your online fork:
Commit changes in interactive way:
Committing is recording the changes you've made (all of them or which you select) along with the descriptive message into your local repo. It's like saving a file in git.
Code: Select all
~$ git commit -i
> p (patch)
> * (all)
> y
Code: Select all
~$ git commit -m "<commit message>"
Code: Select all
~$ git commit --amend
NEED TO REVIEW THIS, FULL OF DOUBTS, EVERYTHING FROM HERE ON IS WRONG:
Push your commits to... your online fork? (and create the corresponding branch on the fly):
Code: Select all
~$ git push -u origin <new_branch>
When the branch is already in the server this is enough:
Code: Select all
~$ git push
Code: Select all
~$ git checkout master
~$ git pull -p
Code: Select all
~$ git branch # List your branches to check exact names
~$ git checkout <branch_name> # Get into the branch you want
*** ~$ git pull # ¿¿Incorporate the changes of your online branch into your local branch?? ***
*** ~$ git merge master # ¿¿Apply on top of branch all the new commits in local master?? Do I still have branch separated from master or is it now fused?? ***
~$ git push # Update your server branch
All explained in help.github.com/articles/creating-a-pull-request-from-a-fork/.
Stuff for the bad moments:
You realise now that some time ago you broke something in one of your branches, and need to undo some not-recent commits:
Code: Select all
~$ git rebase -i master
This gives you a list of all the commits since the latest commit on master or origin/master
Then you can re-commit the changes you want to keep, I don't know how 'cause never did it but I guess I'll have to learn sooner or later.
You realise anything you've been working on is useless and you want to start from scratch from the current online repo (or the git tree got messed up and you need to reset it and probably lose everything that wasn't pushed to the online repo):
Code: Select all
~$ git reset --hard origin/master