Some exploration with git

Programmers discuss here anything related to FreeOrion programming. Primarily for the developers to discuss.

Moderator: Committer

Post Reply
Message
Author
User avatar
Oberlus
Cosmic Dragon
Posts: 5714
Joined: Mon Apr 10, 2017 4:25 pm

Some exploration with git

#1 Post by Oberlus »

I don't use git yet but want to learn for good, so that I can at least contribute with simple FOCS changes.

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).

Please, check out what I've got up to now and correct my mistakesWhile I keep digging into the several aspects involved, I'll appreciate any correction or advice you could like to give me. I'll update the OP 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 :D
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>
(Something like https://github.com/Oberlus/freeorion)

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)
Configure some aspects of git:
- Set up some fancy color ui stuff (I assume):

Code: Select all

~$ git config --global color.ui auto
- If you want to use a human-friendly editor instead of vi:

Code: Select all

~$ git config --global core.editor "<path_to_editor_you_like/command_line>"
- To reduce unnecessary merge commits duo to concurrent work and pull/push crossfire, enable automatic rebase:

Code: Select all

~$ git config branch.master.rebase true
Rebase means you first update your local branch with online repo and then apply your commits over your now-up-to-date repo, keeping the git story in a single line (instead of with branches that diverge and then merge).


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. 
As noted in the final tip, with that process you are not updating your fork in github, just your local copy of the fork. So...

Keep your online fork up to date with the original master:

Code: Select all

~$ git push
This can be done just before pushing changes to your fork.

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
Add a message (tittle, descriptor) to the group of commits you've just made:

Code: Select all

~$ git commit -m "<commit message>"
If you haven't pushed yet and realise you had something else to change and add to the last pack of commits, use this (don't forget: never do it if you already pushed):

Code: Select all

~$ git commit --amend
I better ban myself from ever using --amend. I'll try to be cautious when preparing a commit pack and its message, and if later something was missing I'll fix it in a new commit.

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>
Origin is... the master of your fork?.
When the branch is already in the server this is enough:

Code: Select all

~$ git push
Keep your local master up to date with your fork:

Code: Select all

~$ git checkout master
~$ git pull -p
Update your branches:

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
Make a pull request:

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
(Or origin/master if you broke it in your 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
Last edited by Oberlus on Wed Jun 20, 2018 2:38 pm, edited 8 times in total.

User avatar
Dilvish
AI Lead and Programmer Emeritus
Posts: 4768
Joined: Sat Sep 22, 2012 6:25 pm

Re: git for first time contributors to FO development

#2 Post by Dilvish »

I don't really have time right now to go through and carefully point out all the corrections I think are necessary. I am not sure if or when I would come back to try clearing this up. It doesn't really seem like a good process (or likely resulting finished work) to have someone try to do a big write-up on a complicated topic they don't know very well, in reliance on people who know it better coming to try cleaning it up.

I think what would be much much better would be for you to change this to a set of links to those posts (by people who do know git & github well) that you found most helpful. And then with each of those it would be helpful if you summarized the basic topic or question that the post answered for you, but I don't think you should try getting into paraphrasing/summarizing the posts themselves at this stage of your understanding (i.e. the summary description should generally be more brief than the ones you have done here).
If I provided any code, scripts or other content here, it's released under GPL 2.0 and CC-BY-SA 3.0

o01eg
Programmer
Posts: 2004
Joined: Sat Dec 10, 2011 5:46 am

Re: git for first time contributors to FO development

#3 Post by o01eg »

I suppose there should be some words about remotes as there should be two of them. One is the freeorion's repository where user pulls upstream changes and other is his fork where he pushes changes for pull-request.
Gentoo Linux x64, gcc-11.2, boost-1.78.0
Ubuntu Server 22.04 x64, gcc-12, boost-1.74.0
Welcome to the slow multiplayer game at freeorion-lt.dedyn.io.Version 2024-03-15.b3de094.
Donations're welcome:BTC:bc1q007qldm6eppqcukewtfkfcj0naut9njj7audnm

User avatar
Oberlus
Cosmic Dragon
Posts: 5714
Joined: Mon Apr 10, 2017 4:25 pm

Re: git for first time contributors to FO development

#4 Post by Oberlus »

o01eg wrote:I suppose there should be some words about remotes as there should be two of them. One is the freeorion's repository where user pulls upstream changes and other is his fork where he pushes changes for pull-request.
Thank you, o01eg! That indeed seems very important.

I am sure I have more than half of the important concepts still in the dark.


And this is the Dilvish I was missing! Welcome back :)
Dilvish wrote:I don't really have time right now to go through and carefully point out all the corrections I think are necessary. I am not sure if or when I would come back to try clearing this up.
¡Very valuable information! I'm going to put it into my bank account to see if it can generate any interest to me after a few years.
Dilvish wrote:It doesn't really seem like a good process (or likely resulting finished work) to have someone try to do a big write-up on a complicated topic they don't know very well, in reliance on people who know it better coming to try cleaning it up.
That's cute. But no body "has" me here. And you can bet I wasn't relying on anyone taking his valuable time to come and solve my doubts (but I had some hopes on someone coming to perform the functions of a moral justicar).
Dilvish wrote:I think what would be much much better would be for you to change this to a set of links to those posts (by people who do know git & github well) that you found most helpful.
Very good idea!
That's why I had linked those posts in the OP from the very beginning:
Oberlus wrote:I've been reading the thread Mi git usage (my thanks to Cjkjvfnby, adrian_broher, wheals...).
Where "Mi git usage" is a link to another thread in this forum.
Most of what I've written here is just a copy-paste of what is in the first three posts of that thread, with some rewording of the explanations to help me check what I think I understand.
Dilvish wrote:And then with each of those it would be helpful if you summarized the basic topic or question that the post answered for you
Dilvish, get out of my head! You are reading my mind :D
I mean, what you describe here is exactly what I've tried to achieve, a summary of basic topics (more or less ordered in what could be the development process). ¿I guess it is not evident because I just used titles for each separate topic, without fat bullets?
Dilvish wrote:but I don't think you should try getting into paraphrasing/summarizing the posts themselves at this stage of your understanding (i.e. the summary description should generally be more brief than the ones you have done here).
If you were able to further summarise what I've written here (and add the important missing stuff like the one o01eg has pointed out) and still make it understandable for people that has never used control version or concurrent work software like git, then I think you should contact the owners of github and offer your wonderful tutorial to them. Such a valuable treasure should not be a secret! Because I have not find short tutorials for this, they are always abundant on words and time demanding.

User avatar
Oberlus
Cosmic Dragon
Posts: 5714
Joined: Mon Apr 10, 2017 4:25 pm

Re: git for first time contributors to FO development

#5 Post by Oberlus »

So I'm digging into clone and fork.

Fork: creates an online repo as an identical copy of another online repo, and you are the owner of that repo. To make changes in the fork get into the original, you'll do Pull Requests (PRs).
Clone: creates a copy of an online repo in your local machine. If you do a push, you are doing it against the original online repo. So I guess clone should be used only by users that are not contributing to the project (no push) or the owners of the original online repo (that do use push).


My original idea for the OP was to make it a tutorial (for me) on how to make your first PR, so fork is the way to go. I'm editing the OP to incorporate the info on this matter.


Edit: I've found this very helpful article at github on git workflow. Maybe it renders useless this thread :D
I'll incorporate all the info and correct mistakes when I get the time.

Gault.Drakkor
Space Floater
Posts: 40
Joined: Sat Jul 01, 2017 4:54 am

Re: How to make pull requests to contribute to FO

#6 Post by Gault.Drakkor »

What bothers me, is that this is not what it says on the tin.
The subject phrasing at this point indicates that this is the authoritative correct 'how to:'. That is not true at this time. This post could confuse somebody who is looking for the correct 'how to'.

Oberlus wrote: I've been reading the thread Mi git usage
This looks like the same thread topic? Why create another thread for same topic?

User avatar
Oberlus
Cosmic Dragon
Posts: 5714
Joined: Mon Apr 10, 2017 4:25 pm

Re: How to make pull requests to contribute to FO

#7 Post by Oberlus »

Gault.Drakkor wrote:What bothers me, is that this is not what it says on the tin.
The subject phrasing at this point indicates that this is the authoritative correct 'how to:'. That is not true at this time. This post could confuse somebody who is looking for the correct 'how to'.
Oberlus wrote: I've been reading the thread Mi git usage
This looks like the same thread topic? Why create another thread for same topic?
I'm sorry I haven't finished yet learning so the post is still a work in progress. I know, you're right, I should have finished the homework first.
And it's not the same as the linked thread, at least in that I'm trying to have all the relevant information compiled in a single post. I thought it was going to be useful in my learning process (so far it is) but didn't think of anyone being bothered by it. And also, the instructions I first gathered from that thread were wrong in that are not intended for an external contributor but for the owner or a collaborator with permissions in freeorion/freeorion.

User avatar
Dilvish
AI Lead and Programmer Emeritus
Posts: 4768
Joined: Sat Sep 22, 2012 6:25 pm

Re: How to make pull requests to contribute to FO

#8 Post by Dilvish »

Oberlus wrote:And also, the instructions I first gathered from that thread were wrong in that are not intended for an external contributor but for the owner or a collaborator with permissions in freeorion/freeorion.
I don't see that there. ~98% or more of the time my git interactions are identical to what any external contributor could do, and at least the great majority of that thread looks entirely compatible with that. If something in that thread confuses you or looks wrong to you, then you should ask for clarification of it there.
If I provided any code, scripts or other content here, it's released under GPL 2.0 and CC-BY-SA 3.0

User avatar
Oberlus
Cosmic Dragon
Posts: 5714
Joined: Mon Apr 10, 2017 4:25 pm

Re: Some exploration with git

#9 Post by Oberlus »

I was talking about fork (as commented by o01eg). The first posts of the older thread included instructions to push against the remote, and no mentions to "upstream" or "fork", and thanks to o01eg I noticed that).
I'm not telling that you are not using those instructions just fine, but it is my understanding that and external collaborator won't have write access and thus won't be able to push against the repo, and instead s/he will have to use pull requests.
Dilvish? wrote:Some exploration with git
Fair enough.
But I hope (once I get free time again) to finish my learning and the post and then I think the previous tittle will be more informative.

Post Reply