Working with GitHub repository [updated: 04/02/2015]

[micheus]

The instructions I'm putting here are for use with "linux like" environment under Windows as MSysGit, MinGW or CygWin. (and for any Linux too)
If you want only to translate Wings3D' language files go here: [Translating Wings3D] Working with GitHub

Also, this is not a technical guide (neither detailed) - for that, check these links:
- Git Community Book (user friendly)
- Git Documentation (user friendly)
- git(1) Manual Page (full list of commands)
- Git Internals - Maintenance and Data Recovery

Setting up GitHub

• Starting
  If you still don't have a GitHub account, you will need to create one: link
  After you've created your account, don't forget to Generating SSH Keys (help in case of any issue about it)
  
• Preparing to clone
  You will find all Wings3D projects under dgud's repository. (you can fork any other, but that is the official repository)
  Find the project you want clone and fork it first.
  - Select the repository you want;
  - at the top-right the project page you will find the Fork button;
  Now, you have a project "copy" in your own repository. Check it out.
  You will see a git link that you should use for cloning (e.g.: [SSH] git@github.com:<your git ID>/wings.git).

Setting up your environment

• Cloning the Wings project repository
  Lets say that the project sources will be put under a folder named c:\sources\ and it still empty (at the first time this will be true).
  After you start the terminal, enter in the source folder:
  $ cd /c/sources
  $ git clone http://github.com/<your git ID>/wings.git wings
  $ cd wings
  This will copy the entire project source code in your PC in c:\sources\wings and set the current directory to wings.
  
  You still need to:
  • Git records your name and email address with every commit you make, so the first step is to tell Git what these are:
    $ git config --global user.name 'Your Name'
    $ git config --global user.email you@somedomain.com
    
  • define the remote repository for the main developer (you can define more then this, if you want):
    $ git remote add dgud git://github.com/dgud/wings.git
    
  • transfer the remote repository reference/index to your PC
    $ git fetch dgud

*** Any git command must be invoked at the project root directory ***

This is a sample what I have on my system (you can use these command at any time):
$ git remote % this will list all remote repositories added

Code:

dgud
optigon
origin           % this represents your repository

$ git branch % this will list all branches existing on your PC (local)

Code:

dgud/bugfixes
  dgud/pu
* master         % this one marked with "*" is the current one - that you are working on
  mv/ask_addons
  mv/bugs1.4.1
  origin
  rj/preview_dialogs

Starting to work...
These are the basic operations your will use.

• $ git checkout <branch_name>
  This will set your current branch for working.
  * When you are switching between branches all files changed in the first branch will be replaced for that in the second one.
  
• $ git checkout -b <your_name_initials>/<your_new_branch>
  As your master should not be the branch that you add commits to, this should be used to create a new branch [-b] based on the current one.
  * The branch naming was suggested to me by optigon in the past.
  
• $ git commit -a -m"your commit description"
  After you finish your changes (or periodically, if you want) you need to use this command for save them. The description here is single line only. For multi-line you will need to set up the emacs editor for your environment.
  * Only after commit your changes you will be able to push your changes to the origin repository (yours).
  
• $ git push origin <your_branch_name>
  This command will sent your branch (new one/updates/changes) to your repository on GitHub.
  * Once in the GitHub repository, your can access it on your browse and use the option to pull a request for other member that had forked the same project (not only that one you've made your fork).

Other useful commands...
These are operations that you would need to use.

• Forcing your current branch be replaced with that one in the referenced repository:
  $ git reset --hard <repository>/<branch_name>
  * Warning: any changes you've made will be lost!
  
• Showing the commit informations for the current branch (hit [q] to exit):
  $ git log
  
• At any time that you want update reference/index of a remote repository, just use:
  $ git fetch <remote_repository>
  
• If you already have a branch with your changes, but it is based on an older repository, then you can use:
  $ git checkout <your_branch_name>
  $ git rebase -i <repository>/<branch_name>
  * This should update your branch, but preserving your changes.
  
• To see the remote branches:
  $ git branch -r
  
• Renaming a local branch:
  $ git branch -m <old_name> <new_name>
  
• To remove/delete a branch from your PC (local) repository use:
  $ git branch -D <branch_name>
  ex. $ git branch -D mv/fix_pov-ray
  
• To remove/delete a branch from your Github repository use:
  $ git push origin --delete <branch_name>
  or
  $ git push origin :<branch_name>
  ex. $ git push origin --delete mv/fix_pov-ray
  * it's also possible to remove more than one at time:
  $ git push origin :<branch_name_1> :<branch_name_2> :<branch_name_3>
  
• If added files to the project, you will need to add them to be synchronized with other branches:
  $ git add <relative_path_and_file_name>[/i]
  ex. $ git add plugins_src/primitives/wpc_heightmap_surface.erl
  
• Removing the last commit sent to the remote repository:
  $ git reset --hard HEAD~1
  $ git push -f
  
• Check the difference between the files you've changed and those previously committed:
  $ git diff
  
• Checking the working tree status:
  $ git status
  
• Verifying various types of objects (usually you will see information about the last commit):
  $ git show
  
• The command gitk will show you (in a graphical UI) the commits history and let you compare different ones
  
• You can build a different version of Wings3d by using the tags IDs. Use $ git tag -l to get the tags list and then use:
  $ git checkout tags/<tag_name>
  
• You are recreating your local environment and want to "download" your repositories from the github cloud (origin). Fetch origin will not work. What you need to do is create your local repository as usual, plus informing the source repository to be clonned:
  $ git checkout -b mv/fix_pov-ray origin/mv/fix_pov-ray
  
• If you ran make and are getting unexpected error related to lang files, then this command will clean everything up (then run make again):
  $ git clean -dfX
  
• Getting a summary of all commits in your local branch
  $ git log --pretty="%h - %s"
  

Added 06/15/2015 - got to link

• Updating your master branch with the official one
  
• Fixing the last commit you just pushed to origin

Added 06/15/2015 - got to link

• Copying commits from a branch to another

Added 06/29/2018

• Using git to prepare your PR to have a clean history by Maximilian Peters

---

This small reference was assembled along the time I was starting to contribute with the Wings3D's community.
I would to register my thanks to optigon and dgud which helped me a lot by taking out my doubts (even nowadays).

[povmaniac]

Brilliant initiative!! Thanks..

[micheus]

I tried to create a script for those users who wants help us with the translations of language files - so, they need only a github account, environment and set their personal informations for it.

It is just for translators who doesn't need preserve their branches, since we wont use rebase (we are always overwriting the master branch).

Preparing the environment (just for the first time - steps 1 to 4)

1. Download and install Git for Windows from this link.
   
   
2. Let say the path name and location is "c:\git". Use the windows explorer and look for the file "git-bash.exe" into that folder and run it.
   
   
3. In the prompt ($), lets clone the remote wings repository to the local one and enter in the wings directory:
   $ git clone http://github.com/<your github repository>/wings.git wings
   $ cd wings
   this action is going to create a folder wings under the current directory (c:\git\wings) with all source files.
   
   
4. Git records your name and email address with every commit you make, so the first step is to tell Git what these are:
   $ git config user.name 'Your Name'
   $ git config user.email you@domain.com
   
   obs: you can check these informations by running the command: $ git config -l
   
   From this point the procedures will be the same for every time you need to update the sources in order to get any new/updated language file from the master programmer.
   
   
5. Being sure to have selected the master branch to work
   $ git checkout master
   
   
6. Updating the local references to your wings repository on github
   $ git fetch origin
   
   
7. Making sure the local files are the last one made available by the master programmer (dgud):
   $ git reset --hard dgud/master
   
8. Updating your remote master branch with that one we just "download" to the local repository:
   $ git push origin master
   
   
9. Creating a new branch for each new version of Wings
   $ git checkout -b v1.5.2
   For example, this will create a new branch named v1.5.2 based on the master branch.
   
   Now you can work in the languages files which you would find in the .\wings\src, .\wings\plugins_src and its subdirs.
   You must use the original files (English)as reference and naming the new .lang files like shown in this post.
   
   You can check the files currently changed by using the command:
   $ git status
   
   here a sample of the output information. It shows a modified file and a new one:
   

   $ git status
   On branch master
   Your branch is ahead of 'origin/master' by 8 commits.
   (use "git push" to publish your local commits)
   
   Changes not staged for commit:
   (use "git add <file>..." to update what will be committed)
   (use "git checkout -- <file>..." to discard changes in working directory)
   
   modified: src/wings_pt.lang
   
   Untracked files:
   (use "git add <file>..." to include in what will be committed)
   
   src/wings_es.lang
   
   no changes added to commit (use "git add" and/or "git commit -a")

   In order to enable files in the branch be updated by a commit command you will need to add the files for commit as informed in the output screen (just the first time it is reported as "not staged for commit" or "untracked").

A new .lang file will appear in the Untracked files session and as indicated you should to use git add <file_name> in order to include it to your branch.

In order to write the commit messages required by that git command we may need to install an editor like Vim or Emacs and add their paths to the PATH variable (for the git console/shell).
After run the git commit command the editor it will opened and you can describe the informations you think is necessary about what you did. (a list of Vin's commands can be found here and for Emacs here).

After all your files has been updated/added and committed is time to push it to your remote repository:
$ git push origin master
that command will replace your remote (origin) master branch with the local one.

The next step is to make a Pull Request at GitHub to the main developer's repository.

[TulipVorlax]

What is the best way to verify that the local files really are last version of the "ancestor" repo ? Is it with the SHA hash displayed on top the Windows app or just under the "pull resquest" on this page ? They're not even the same !?
Thanks.

[micheus]

TulipVorlax, I think you can use the show command for that. Take a look at the pictures below and see if they answer your question...

If everything was "fetched" all informations should be updated and we can use git show -s [object] to verify the latest updates.

Here is a sequence of actions for exemplify the situation:

• We ran git commit and we are advised that the new file we add is untracked. In order to force it be added to Wings3d project we need to use git add <file name>. Then we can repeat the commit command.
  
  An text editor will be displayed as shown below and after we save the changes a small summary will follow the commit command line in the shell.
  obs: note the advice bout the "#". We need to remove it in order to enable the command be executed ("new file:").
  .
  
• In order to verify what was the latest commit/update to a branch we can use the git show command. Below the picture show my local master branch information, my remote (origin) master branch and the dgud's master branch (the main developer - the source code for the last Wings3d release)
  

If the steps 7 and 8 were executed the origin/master and dgud/master information would be identical.

[TulipVorlax]

Good.
All 3 git show command gave the exact same output, so i created the new branch.

Now i wanted to do a test and duplicate the english lang file, but it's not there. I think i remember reading that this file was created while compiling the release or something, so it's normal. But now i'm unsure wich files _en.lang files should i use, i can't translate from any other language, lol. I suppose i just have to use the files from my last installation of Wings. This mean that translation would always be a bit behind, if any string was changed in the source after the last release. Maybe it's not that much of a problem, it's often like this on other opensource projects.

EDIT :

I found a file in the source that never was on my computer before : mac_file_fr.lang
I can't update this file because i don't have the english one and i dont have a mac to test it.

[micheus]

Now i wanted to do a test and duplicate the english lang file, but it's not there. I think i remember reading that this file was created while compiling the release or something, so it's normal.

Yes. It is created when we build the installer or if we run the command "make lang" (for those that have a dev environment).
You also can get it from the official version (always the last one) you have installed in you PC.

I found a file in the source that never was on my computer before : mac_file_fr.lang

I can't generate a English lang file for it.
Anyway, this kind of file is used for the file dialogs, so I don't think you need update it.

[micheus]

Updating your master branch with the official one

By considering you create different branches for the changes you do, it's a good idea update the master branch when the official one is updated. This way, every new branch you create will be "synchronized" with it:
$ git checkout master
$ git fetch origin
$ git reset --hard origin/master (ensuring your local master is the same your remote/origin)
$ git fetch dgud (updating your local references to the master dev)
$ git rebase dgud/master ("synchronizing" your local with the official one)
$ git push origin master (updating your remote branch master)
If you get this kind of error message:

! [rejected] master -> master (non-fast-forward)
error: failed to push some refs to 'http://github.com/Micheus/wings.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Merge the remote changes (e.g. 'git pull')
hint: before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

you probably will need to use git pull as suggested:
$ git pull origin master

From http://github.com/Micheus/wings
* branch master -> FETCH_HEAD
Merge made by the 'recursive' strategy.
src/wings.erl | 339 ++++++++++++++++++++++++++++-------------------------
src/wings_file.erl | 22 +++-
2 files changed, 196 insertions(+), 165 deletions(-)[/color]

As is all OK now, we can try the last git push command again. That is valid for any local branch.



Fixing the last commit you just pushed to origin

$ git rebase -i HEAD~1
The editors will start with the last commit reference prefixed by pick and followed by a comment showing the commands you can use:

# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell

if you want only to change the commit message, replace the pick by reword; if you want make other changes to the code using the same commit then replace it by edit.
If you chose reword, after you save and exit the editor it will be started again with the last commit message to be edited.
If you chose edit, then you will see something like this:

Stopped at 8e59ce9... Fixed menus issue related to use of [option] flag.
You can amend the commit now, with

git commit --amend

Once you are satisfied with your changes, run

git rebase --continue

Just proceed with our changes to the source code. After we've finished it we need to tell to git which files to update by using git add command. We can check this by using git status command.
Then, as suggested in the message above, we can use git commit --amend to update the commit message and after this we use git rebase --continue in order to commit the changes.

Now we just make a new forced push to origin and it's done!

[micheus]

Copying commits from a branch to another

Let say we made some changes and committed them in the wrong branch and we want to move or just copy it to the current branch - we do that using cherry-pick command.

The first we need to find the commit ID which we can do by using the log command. A list of commits will be shown:
$ git log <source branch>

commit c61c5e42edbc31f49bf3dd373e564dd3742b0d79
Author: user <user@mail.com>
Date: Wed Oct 28 18:06:42 2015 -0200

Fixed .auv file parser for menu option control
...

We need to take note of the only first seven number: c61c5e4

Now, in the current branch, we run the follow command:
$ git cherry-pick c61c5e4

[mv/shaders f2af162] Fixed .auv file parser for menu option control
1 file changed, 10 insertions(+), 1 deletion(-)

Done!

Copying only a file from a commit to another branch
$ git checkout <commit> <folder or file path in the current branch>

Retoring a file from a branch
$ git checkout <branch> <file path in the current branch>

[dgud]

Why do you not use gitk?
It is very easy to point and rightclick/cherry-pick the commits you want.