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.
- 1 The basics
- 2 Creating a merge request
- 3 See also
pmbootstrap init, the whole
pmaports.git repository was cloned to your computer. You can use
pmbootstrap config aports to see the path, and if you chose the default work path, you will get:
$ pmbootstrap config aports ~/.local/var/pmbootstrap/cache_git/pmaports
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
alias pma="cd ~/.local/var/pmbootstrap/cache_git/pmaports" 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
git branch, but we do have a lot of branches, so the one below is probably easier). Switch back to master if necessary with
git checkout master.
$ git rev-parse --abbrev-ref HEAD master
(You may want to extend your shell to automatically display the branch name when you are inside a git directory, e.g. by using
grml-zsh-config 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'"):
$ git status On branch master Your branch is up to date with 'origin/master'. nothing to commit, working tree clean
When you have made changes,
git status will list the files that were changed:
$ git status On branch master Your branch is up to date with 'origin/master'. Changes not staged for commit: (use "git add <file>..." to update what will be committed) (use "git checkout -- <file>..." to discard changes in working directory) modified: device/device-lg-mako/APKBUILD no changes added to commit (use "git add" and/or "git commit -a")
Create a new branch, commit the changes and go back to the master branch:
$ git checkout -b mynewbranch M device/device-lg-mako/APKBUILD Switched to a new branch 'mynewbranch' $ git add -A $ git commit -m "describe your change here" [mynewbranch c9c729a5] describe your change here 1 file changed, 1 insertion(+), 1 deletion(-) $ git checkout master Switched to branch 'master' Your branch is up to date with 'origin/master'.
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:
fairphone-fp2: new device (if the codename is
git commit instead of
git commit -m "describe your change here" and your editor will show up, where you can type in a pretty commit message. You can change the default editor by changing the
EDITOR 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.
$ git pull Updating e8a7926e..8909e932 Fast-forward coreapps/coregarage/APKBUILD | 24 ++++++++++++++++++++++++ ... 26 files changed, 307 insertions(+), 181 deletions(-) create mode 100644 coreapps/coregarage/APKBUILD ...
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:
$ git checkout mynewbranch Switched to branch 'mynewbranch' $ git rebase master First, rewinding head to replay your work on top of it... Applying: description here
If there are any conflicts, pay attention to the git output and run
git diff to see where the conflicts are. Edit the files in a text editor, run
git add -A and then continue the rebase.
Creating a merge request
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.
$ git remote add USERNAME firstname.lastname@example.org:USERNAME/pmaports.git
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:
$ git push fatal: The current branch mynewbranch has no upstream branch. To push the current branch and set the remote as upstream, use git push --set-upstream origin mynewbranch
So we will tell git the remote we would like to use.
$ git push --set-upstream USERNAME mynewbranch Enter passphrase for key '/home/user/.ssh/id_rsa': Counting objects: 59, done. Delta compression using up to 2 threads. Compressing objects: 100% (39/39), done. Writing objects: 100% (59/59), 13.48 KiB | 1.68 MiB/s, done. Total 59 (delta 29), reused 0 (delta 0) remote: remote: To create a merge request for mynewbranch, visit: remote: https://gitlab.com/USERNAME/pmaports/merge_requests/new?merge_request%5Bsource_branch%5D=mynewbranch remote: To gitlab.com:USERNAME/pmaports.git * [new branch] mynewbranch -> mynewbranch Branch 'mynewbranch' set up to track remote branch 'mynewbranch' from 'USERNAME'.
When you want to push more changes, you can simply use
git push for this branch.
There is also
git push --force, which can be used to override commits without creating new ones. You can use it after rebasing your branch on master (as explained above).
git rebase -i master is a powerful command to edit previous commits, the
-i 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.