Git workflow

This guide explains how to update your local copy of pmaports.git, and how to contribute back changes (e.g. after creating a new device port). It is suitable for people who have not used git before.

pmaports dir
During, the whole   repository was cloned to your computer. You can use  to see the path, and if you chose the default work path, you will get:

All commands below need to be executed in your pmaports dir.

It's a good idea to make accessing this directory easy with a short command, so consider setting up a shell alias. For bash this can be done by adding  to.

Updating pmaports (rebasing on master)
Since we are dealing with a git repository, pmbootstrap leaves the directory alone after the initial clone. It will not automatically update it. The only thing it will do is tell you when your pmaports.git dir is so outdated that you absolutely have to update it, or otherwise it would be incompatible with your pmbootstrap version. But you can always manually update the pmaports.git directory, and it is recommended to do so before you start or continue with making changes to the repository.

Make sure that you are on master
If you never ran any git commands in this directory before, you will still be on the master branch. Otherwise, run this command to check the branch name (there is also, but we do have a lot of branches, so the one below is probably easier). Switch back to master if necessary with.

(You may want to extend your shell to automatically display the branch name when you are inside a git directory, e.g. by using  and ZSH.)

Put your changes into a new branch
Check if you made any changes to your pmaports dir. Changes could come from starting a new device port, for example.

When you have made no changes, you can move on to the next step ("Running 'git pull'"):

When you have made changes,  will list the files that were changed:

Create a new branch, commit the changes and go back to the master branch:

Note that there are best practices for commit messages, and for commits that actually make it into the master branches of pmaports.git, we try to stick to them. For example: when porting a new device put the codename of your device at the start of the commit message:  (if the codename is  ). Type  instead of   and your editor will show up, where you can type in a pretty commit message. You can change the default editor by changing the  environment variable.

Running 'git pull'
Let's fetch the changes from the official postmarketOS repository and apply them to the current branch. Git will even show a nice overview of the files that have been changed, and how many lines have changed.

If you did not have any local changes, then you are done here.

Updating your branch(es)
Put all new commits from master into your own branch, and then apply the changes you made on top of that:

If there are any conflicts, pay attention to the git output and run  to see where the conflicts are. Edit the files in a text editor, run  and then continue the rebase.

Preparation
These steps only need to be done the first time.

Forking the repository
We are currently using GitLab for development. Login to the website, and click here to fork pmaports.git to your own user's namespace.

If you have just registered at GitLab, create a SSH key and store it in the settings.

Add your fork as remote
Run this, but replace USERNAME twice with your GitLab username.

Push changes to your fork
The first time you try to push your changes (upload them), git won't know where you want to put them:

So we will tell git the remote we would like to use.

When you want to push more changes, you can simply use  for this branch.

There is also, which can be used to override commits without creating new ones. You can use it after rebasing your branch on master (as explained above).

is a powerful command to edit previous commits, the  option stands for interactive. See git-rebase.io for an in depth tutorial on interactive rebasing.

Create the MR
Simply click the link shown in the git output above, to create the new merge request. Pay attention to the text shown there, following it closely will make sure that your merge request gets merged to master as fast as possible.

Check and fix CI / linting issues
Your submitted code will be built automatically by the continuous integration system to check for errors, style issues, etc. Check the results of the automatic build by going to https://gitlab.com/USERNAME/pmaports/pipelines (replace USERNAME with your username) and clicking on the (chronologically) last item. After the build has finished, you get a list of passed (green check-marks) and/or failed (red X) checks. Click on the failed checks and follow the recommendations in the output shown to fix your code.