Revision as of 19:52, 30 December 2018

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.

• https://github.com/

Once you are registered to github simply connect to it.
Then go to this URL:

• https://github.com/OpenPLi

There you will see all the OpenPLi projects, select enigma2. Or use the direct link:

• https://github.com/OpenPLi/enigma2

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.

• https://github.com/OpenPLi/enigma2

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.

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