Git-commands
Contents
Some basic git commands
Foreword
The file used by OpenPLi and plugins are stored online on a git system. The git system allows version control and is an efficient collaborative tool.
As every tools you need to understand how it work, and have some commands knowledge if you want to actively contribute to development/translation.
Installing the git client on your computer
On Mac OSX
Open up a terminal and type:
git --version
If git is not installed you should be prompted to install it.
On Windows
Go to GitForWindows and install it: https://gitforwindows.org/
Remark: seems that git-gui doesn't start on Windows, you need to launch it in Windows 8 compatibility mode. (but we won't use it anyway).
On Ubuntu / Linux
sudo apt-get is Ubuntu command, it should also work on other distribution just adapt the package manager to it.
Open up a terminal and type:
sudo apt-get update sudo apt-get install python gettext gawk sed git
Forking a repository
The first think to do if you want to collaborate is to go github and create an account on it.
Once you are registered to github simply connect to it.
Then go to this URL:
There you will see all the OpenPLi projects, select enigma2. Or use the direct link:
On the top right you will see the Fork button, click on it. Here you are, you have "forked" the OpenPLi/enigma2 project into your own git online environment.
Cloning a repository
When you want to clone a repository, access it with your favorite webbrowser.
You will see a green button called: clone or download, click on it. This will show you a specific url, take a copy of it (or press the button after it this should copy it for you).
Open up a terminal and type:
git clone https://github.com/OpenPLi/enigma2.git
This will clone the OpenPLi enigma2 locally on your PC, in a folder named 'enigma2'
Branch
Never work on the main trunk always create a branch for you to work, it will really ease you life when you will want to create a PR but also to keep your trunk up-to-date with the original repository.
Creating a branch
Open up a terminal, go into your local repository clone and type.
git checkout -b mychanges
This will, create a branch named "mychanges" and switch into it. So now you are ready to make your changes.
The alternative way to create is, the 2 steps approachs:
git checkout mychanges git branch mychanges
git checkout will create the branch, git branch we let you switch to it.
Display available branch
Open up a terminal, go into your local repository clone and type:
git branch
Display all the available branches:
git branch -a
Switching to a branch
Suppose that you want to switch to a branch called: branch_name
git branch branch_name
Upstream
When you clone a repository this one is internally referenced as origin by git system, later on if you want to push a change towards the origin repository you will need to have write access to it. But since you clone from OpenPLi official repository, you won't have a write access to it. To work around this problem, you will need to push your changes to an online git that you have write access to and, guess what, by forking the OpenPli repository you have created your own valid writable copy. So lets we will now create let know your git that this upstream exist.
Creating an upstream to your own fork
Go to your personal github and enter the OpenPLi enigma2 fork that you create before.
git remote add upstream https://github.com/YouGitAccountName/enigma2.git
It is done, now your local git know 2 repository: origin the one from OpenPLi and upstream your own fork of it.
Displaying the upstream
You can view the origin and upstream with this command:
git remote -v
This will show you both the origin url and the upstream url, this is useful to know who's who.
Pushing a local branch to your upstream server
Since we have created a branch named mychanges we will push it to our own git:
git push --set-upstream upstream mychanges
Pushing your changes to your remote branch
Once you have pushed your branch to your own upstream, you can modify some files and push them to your online repository.
Every files that are modified or added locally must be added to your local git system.
git add Name_Of_The_File git commit -m "I add a file to my git" git push
git add to add all the changed files to your git.
git commit -m you specify a commentary between quote
git push to send the file to your online git
Sending back your changes to OpenPLi
Now you have to go online to your github, you will see that it informs you that there is new branch with changes and it offer you the green button: Compare & pull request.
Push on it, if everything went fine, you should see Able to merge this means that your change can be proposed to OpenPLi.
You will have an editor where you need to describe your change, please be specific to explain in details what your proposed change is doing. So please don't limit to comment to patch, or improvement put some details.
Then click on the green button: Create pull request
Syncing origin and upstream
origin will get new updates, if you want to keep your upstream in sync with origin, you need to retrieve the origin changes and send them back to your online github.
remark: never change files yourself on the default branch develop always create a branch for your changes otherwise this syncing step will not work.
We will check in which branch we are:
git branch
Then we go back to our local develop branch and retrieve the changes done on OpenPLi, and get then back locally:
git checkout develop git fetch git pull
Our local develop branch is now in sync with the OpenPLi one.
Now we need to send then back to our upstream:
git push upstream
Now you can check your online git, it will mention that this branch is even with OpenPLi:develop. And that's exactly what we want to achieve here.
To be continued...
