Maintain packages with Git

Git is a distributed version-control system for tracking changes in source code during software development. It is designed for coordinating work among programmers, but it can be used to track changes in any set of files.

Some, but not all, packages developed for the Humax use Git to maintain the associated source code. This allows for better tracking and control of changes and, potentially, allows for multiple users to collaborate on maintaining the package by making and testing changes on a private copy of the package and then submitting them for review and incorporation into the main package for distribution to the Humax community via the normal package update mechanism.

This wiki page attempts to describe the basics required to submit a change to a package that you don't own using the webif package as an example. It was written by a naive new user of Git and does not attempt to cover all of Git / Github and may contain errors, please correct and update this page where needed!

Git repository = Storage location for a single humax package

Initial setup

Install, using the normal Humax package install method, the following (may need to show Advanced packages):

• git
• pkgtools
• gzip
• A text editor, Joe, Nano, or Vim unless you are happy with the default Vi

Create a user account on the hummy package git repository site https://git.hpkg.tv/ userid should normally be the same as your forum id, Optionally also create an id on the the public git repository github

All commands shown should be issued from a command prompt (telnet, putty, or Command Line on webif Diagnostics page)

Create a directory to hold git repositories (do not use /mod directly to avoid conflicts with installed packages)

md /mod/git
cd /mod/git

Set up some defaults for Git based on your details and preferences. The credential.helper timeout will remember your password for 24 hours

git config --global user.name "USERNAME"
git config --global user.email "EMAIL"
git config --global core.editor "editor"
git config --global credential.helper 'cache --timeout=86400'

Fork and clone reposiory

Sign in and find the package you want to work with on the host repository eg https://git.hpkg.tv/hummypkg/webif

If the package you are interested in is not visible on the website contact the package owner to discuss access.

Click on the Fork button (top right) and create a forked repository (using a fork creates a private copy and insulates your changes from those on the master, it is not needed if you are the repository owner) Copy the the HHTPS url for the forked repository, ensure you are in your git folder on the humax and paste it into a git clone command

cd /mod/git
git clone https://git.hpkg.tv/USERNAME/webif.git

Change to your repository directory and add the master repository as another remote - this enables you to pick up changes made to the master

cd /mod/git/webif
git remote add upstream https://git.hpkg.tv/hummypkg/webif.git

You now have two remotes for this project on disk:

1. origin which points to your fork of the project. You can read and write to this remote.
2. upstream which points to the main project’s repository. You can only read from this remote.

Sync with master

You don't need this step if you have just forked and cloned the master, but if time has elapsed and master may have changed you can pull in the latest changes and push them up to your host repository

cd /mod/git/webif
git checkout master
git pull upstream master 
git push origin master

Create a Branch

Every related set of changes should be in its own branch, don't try and fix unrelated problems in the same branch. Branch names should be meaningful.

cd /mod/git/webif
git checkout -b FixBrowseTypo
git push -u origin FixBrowseTypo

The -b flag is only needed for a new branch, not when switching to existing branch

Make your updates

Using your favourite text editor make the necessary changes to the code.

Package, Install and test fixes

For simple changes you may be able to test the changes in isolation without needing to package and install for each update but to fully test using the webif it is best to properly package and install your changes. Update CONTROL/control for the package to update the version number, check the dependencies section if your changes depend on new or updated packages (or remove existing dependencies). See the "Create Packages" page for more information on the control file structure. Create package .opk file and install it (vers#) is the number from the control file

cd /mod/git
opkg-pack webif
opkg install webif_vers#_mipsel.opk

If the opkg-pack fails with 'Resource temporarily unavailable' messages try again - it seems to resolve itself after a few goes. Test to ensure your changes are working as intended.

Commit your changes

Committing saves your updates in the local Git repository and allows you to revert to any previous commit point should you need to back out a change, for a small change you may only need to commit once but for larger changes you can split your work into logical chunks and commit each piece. Pushing then syncs your remote repository with the changes from your local repository.

Before committing Git needs to know which of the changes you have made in the repository folder are to be included in the commit, this is known as staging and can be done in several ways.

To add a file to the next commit

git add file.name

To add all changed files to the next commit

git add .

To see the current status, very useful for checking what will / won't be committed

git status

To discard changes to a file

git checkout -- file.name

To commit all changed files use the -a flag on the commit command (alternative to git add .), if the -m flag is omitted it will open an editor window for you to type a commit message

git commit -a -m "Summary of the changes"

Send changes to remote reposiory

git push

Omit CONTROL/control from commits

When different branches have changes to the same file Git can normally automatically merge the changes provided they don't affect the same lines of the file when you have to resolve the conflicts and decide which version to keep, not hard but extra work for the package owner. Changes to the package version number obviously all affect the same line of the control file and will cause conflicts if several changes are to be combined into one update of the Humax package. So unless you have made other changes (e.g. Dependencies) I suggest that you backout changes to the control file before committing.

git checkout -- CONTROL/control

Create a Pull Request

A Pull Request is a request to the package owner to merge your changes into the Master repository and update the Humax package. The New Pull Request button appears in a number of places on the remote repository pages under the Branches or Pull Requests tabs.

Ensure you specify the master branch of the master repository as the target for merge into and your branch to pull from

Creating a Pull Request

The title and description of the Pull Request should explain to the package owner why your changes should be included in the package. Assign the request to the owner in the assignee tab (on the right of the page)

The owner will review your changes and may request changes which should be made and committed on the same branch (a new Pull request is not needed)

When happy with the changes the owner will merge the branch into master and close the Pull Request, the branch can be deleted and you can start again at the Sync with master step

Further Information

This page only scratches the surface of Git and there are numerous reference works and tutorials on github and elsewhere on the web. A few links that have helped me are:

• The beginners guide to contributing to a github project
• An introduction to Git and GitHub
• Git Tutorials