A potential git workflow for dummies (everyone except Egor at this point)

[Niceno]

Dear guys,

Based on Egor's recommendations, I come up with corrected suggestion for a typical workflow we can use for git. Please note that what I list here is not an exhaustive list of git commands and options, but rather a minimum set to accomplish daily tasks. Also note that this workflow is suggested for longer development, short bug fixes might need a different workflow. I write in first person for the time being, but will change it to second person at later stages.

Anyhow, the proposed workflow might look:

1. Fork DelNov/T-Flows to my own fork Niceno/T-Flows (if it doesn't already exist). This is achieved by pressing the Fork button in GitHub/DelNov/T-Flows

2. Clone my fork (GitHub/Niceno/T-Flows) to a local workstation. At a Linux terminal, this would be achieved with command:

   git clone https://github.com/Niceno/T-Flows

3. Since I am not forking to separate from the rest of you guys, I want to keep connected to the original repository, so I issue this command in Linux terminal:

   git remote add delnov_repository https://github.com/DelNov/T-Flows

4. I understand that it is strongly suggested to rename origin (which is a name set to repository I cloned from my fork by default) to some other meaningful name. To achieve this, I use the following command on my local workstation:

   git remote rename origin bojans_fork

5. At this point, it would be useful to check which remotes I have at my disposal, and I do it with the command:

   git remote -v

   which will give the following list:

   bojans_fork https://github.com/Niceno/T-Flows (fetch) bojans_fork https://github.com/Niceno/T-Flows (push) delnov_repository https://github.com/DelNov/T-Flows (fetch) delnov_repository https://github.com/DelNov/T-Flows (push)

6. Of course, I know on which issue I will be working on. Hence, it makes perfect sense and is very advisable to make a branch for me with a name which reflects these specific developments. In my case I could create a branch called amg_dev_branch with:

   git checkout -b amg_dev_branch

7. Now, happy with the fact that I have my own fork (GitHub/Niceno/T-Flows), my own branch (amg_dev_branch) and with the fact I am still connected with you guys in the original repository (GitHub/DelNov/T-Flows) I do editing, compiling, testing, editing some more, debugging, testing, validating and verifying, and all the other things we normally do when developing simulation tools and physical models.

8. At the end of the day, I am happy with partial progress I made, and I commit my changes in a specific path:

   git commit [path_with_good_progress].

   This will store the changes I made to the local git repository on the workstation on which I work.

9. If I think that the changes are so good they deserve to be pushed to the origin of my fork (GitHub/Niceno/T-Flows) I issue a command:

   git push bojans_fork amg_dev_branch

10. However, there will come a point at which I will believe that I finished my model implementation and would like to share these developments with you guys. In such a case, I go back to web browser to my own fork (GitHub/Niceno/T-Flows), from the drop-down menu called Branch I chose the branch amg_dev_branch and press a button called New pull request to make a pull request.

Any comments? Keep in mind that this is a workflow with a minimum set of commands.

[palkinev]

Answer:

Unfortunately it is not enough and section 8 is incorrect.

If I repeat your procedure to the section 8 I get 2 known forks:

• origin -> your own fork
• upstream -> delnov

and 2 branches:

• release_branch

• algebraic_multigrid_development

thus, section 8 must be git push --set-upstream upstream algebraic_multigrid_development or command I constantly suggest to use git push upstream algebraic_multigrid_development:algebraic_multigrid_development

Clarification:

Actually, you do not need to push changes to Delnov (section 8) at all. Instead you can push to your fork and make "git pull request" from there.

Thus, you can store multiple branches on your fork and push changes with: git push origin name_of_local_branch:name_of_remote_branch_on_your_fork

Suggestion:

I strongly suggest to rename "origin" to some other meaningful name, because "origin" name is set to repository you cloned. If you deviate a bit from this procedure then on your laptop "origin" can be DelNov, on Massimo laptop it can be his own fork. While I was helping Muhamed yesterday he had "origin" pointing at his fork, and then in 20 minutes to Delnov.

use git remote rename origin delnov

Commands you may need:

git pull

commands: git pull origin release branch or git pull upstream algebraic_multigrid_development

are missing in your procedure, keep local code updated if possible.

git merge

If you are going to implement some serious structural changes in the code (or commits are HUGE) then "git pull" can fail.

In this case you should create new branch: git checkout -b branch_with_mad_results

and then:

git merge name_of_the_branch_to_merge_into_currently_selected_branch or git mergetool name_of_the_branch_to_merge_into_currently_selected_branch

And manual merge process will begin. If you have never done this and you have to do it, watch some video guides, because this procure is quite difficult. Git will split screen at 4 parts vertically and show 3 different branches(current branch_with_mad_results, the one you are trying to merge, and upstream from repo) and final result. As merge tool you can use vimdiff, kdiff3 and etc.

git stash

Imagine you have been working on AMG solver and your working copy is messy: you have not committed/added every change you made or/and Tests/ dir is full with output files.

I made some significant pull request and you want to test it before accepting.

git remote add egor https://github.com/palkinev/T-Flows git checkout -b egor_branch git pull egor branch_with_pull_request and it went well (if not then look at git merge section).

but when you try to compile Process it crashes with an error. It can be caused by various reasons:

• changes I made rely on clean Test/ directory
• changes you have not committed or not added (git add) yet mess up with my sources.
• numerous other reasons

in this case you use git stash save i_made_this_stash_before_testing_branch_of_egor

git saves away your changes and your working copy is clean and compiles again.

after you are done testing and you want to return your working copy to the state before pulling my code. git stash apply i_made_this_stash_before_testing_branch_of_egor

Actual stash names are shown with git stash show

[Niceno]

Thanks Egor. What I wrote above would be the minimum possible workflow. Like, only the necessary commands we can't possibly live without. (For example, I don't even mention 'git status' or 'git diff' which are most frequently git commands I use).

Anyhow, I will make changes to my original post above based on your suggestions, and then kindly ask you to check the text again.

[Niceno]

Dear Egor, I made some changes you suggested. I give more meaningful names to both remotes (in steps 3 and 4) and also changed point 10 to make pull request via web browser. I also add point 5 with a command to check remotes. Please have a look.

[palkinev]

If you add a section with a reminder to use "git pull", this workflow will be more or less complete.