Many workflows are possible when using a version control system like
To clarify how we use it in the ROMI project we hereafter details our choices and show ho to performs the most basic tasks to participate in the development of the ROMI libraries.
Here are some very important rules, be sure to understand them first!
- NEVER EVER work on
dev, always on a branch!
- ALWAYS rebase your destination branch onto the one you want to merge before doing it!
devis the integration branch,
masteris the release branch
Clone & configure the repositoryLink
It all starts by cloning the repository you want to contribute to, e.g.
git clone https://github.com/romi/plant3dvision.git # clone the repository
To use all possible git actions on this repository ('repo'), go the location of this local clone
cd plant3dvision #the repo is cloned at the point where you executed the previous command (git clone). If you moved the clone repo, prefix with path like: cd path/to/yourcloned/plant3dvision
Create development branchLink
To contribute to development you have to create a branch on which you will work.
- Let's start by pulling the latest developments by updating our local
git checkout dev # switch to your -local- `dev` branch git fetch # fetch changes from remote (`origin/dev`) git pull # pull changes (if any) from remote to local
- Then create your new branch
<my_branch>and set tracking to remote central repo (
git checkout -b <my_branch> # create local branch `<my_branch>` git push --set-upstream origin <my_branch> # attach local branch `<my_branch>` to remote `origin/<my_branch>`. Login/password will be asked for.
Setting the branch tracking can be done later, even after committing changes to local repository!
Work on your modificationsLink
We advise to use a proper IDE (like PyCharm or Atom) with an integrated or plugin based git tool for this part, as manually adding a lot of files can be time-consuming. Overall you will benefit from a nicer and faster integration of this particular step.
Nevertheless, for the sake of clarity, hereafter we detail how to do that with the
git command-line interface.
Tracking new filesLink
If you create a new file, you will have to tell git to track its changes with:
git add <my_new_file.py>
Adding changes to local repositoryLink
After editing your files (e.g.
<my_file2.py>), tell git to validate the changes to these files by adding them to the list of tracked changes with:
git add <my_file1.py> <my_file2.py>
Then commit them to your local repository:
git commit -m "This is my awesome commit!"
Pushing changes to remote repositoryLink
Once you are satisfied with the state of your work, you can push the locally committed changes to the remote central repository:
git push # push modification to `origin/<my_branch>`
Try to do this
add/commit/push sequence as often as you can!!
How do I not forget changes for committing ?Link
Commits that affect only a limited number of files are preferable to track changes and history. However, some work require to modify several files. Especially when working with an IDE allowing easy exploring and modifications of all the repository content, you may forget some changes you did.
To quickly identify all current files with uncommitted changes in your current branch, just simply check with
git status on your local branch.
The terminal lists in a red color all files requiring an action (git add, git restore, git remove): modified files, deleted files, newly added files.
after acting on listed red files, typing
git status should turn all previous files in green. Your branch is ready for committing.
Then just proceed as above with
git commit and
check your commit has been pushedLink
git push, you can get the list of pushed commits related to your current branch with
git log (press
q to exit the list in the terminal).
Prepare your work for mergingLink
Once you are ready for creating a "Pull Request", let's update (rebase in git) our branch with potential remote changes (
origin/dev) since branching
Start with step 1 & 2 and performs step 3 only if the branch where you are trying to integrate your work have diverged!
- Get the latest version of
git checkout dev # checkout your local `dev` branch git fetch # fetch remote changes git pull # pull remote changes (if any) to local
- Rebase of
git checkout <my_branch> # checkout the branch to rebase git rebase dev # rebase `dev` branch onto `<my_branch>`
devhas diverged during your work:
- if you have conflicts:
- fix them using an IDE
- say to git that conflicts are resolved (e.g. for
git add <my_file1.py>
- continue rebase until all changes are applied:
git rebase --continue # to finish rebase
- push all changes (your rebased modifications) to the remote repository:
git push -f origin <my_branch>
- if you have conflicts:
-f option is necessary after a rebase as local and remote are now different (as show by a
This will force push the changes done after rebasing.
Then you can create your "Pull Request" from this latest commit using the GitHub interface. Don't forget to add reviewer. Now if you have a CI job checking the instability and performing tests, you may have to wait it all goes well before merging.
Finalization: delete integrated branches.Link
Check if you find all yours commits on
origin/dev (either on GitHub interface of using
git log in this branch), if yes:
git branch --delete my_branch # delete local development branch git push origin :my_branch # delete development branch on origin
git branch -a lists all the local branches first (with the current branch in green), followed by the remote-tracking branches in red.
git branch only lists your local branches.
Revert a commitLink
You can revert the last commit with:
git reset HEAD^
Update the project board (Kanban type)Link
- choose the project board corresponding to your pull request (PR)
- link your PR to existing issues
- move the corresponding note to the appropriate column