Git

This document describes how to use git for Alpine Linux development. Using git submit new packages that you've created or submit patches . You can also browse the Developer repositories.

If you are new to git and need quick reference, check Git Basics and also refer further reading section.

Configure your global git config

Configure your name and email address in git. This name and email address will show up in all your commits:

$ git config --global user.name "Your Full Name" $ git config --global user.email "your@email.address"

Using git config without --global let you configure other details for a specific git repository.

Tip: If you want to use git with colored output use:

git config --global color.ui true git config --global core.pager more

Tip: If you want to use git with proxy server:

git config --global http.proxy http://proxy_ip:proxy_port

General git workflow

• Clone the alpine Git repository.
• Make your file edits in your local checkout of the local copy of repository.
• Ensure that your commits meets the Quality assurance.
• Commit the changes in your local repository.
• Bring the rest of your local repository up to date.
• Check what you are going to push
• If you have write access push your changes up to the master else create and submit a patch.

Git Basics

Cloning your forked repository

Fork the repository you want to contribute to. For example to contribute a package or open a merge request for aports you would have to fork alpine/aports. Refer Gitlab docs if you're having problems with that.

After forking you can clone the repository using the command:

git clone git@gitlab.alpinelinux.org:$USER/$REPO.git

Replace $USER with the nickname of your Gitlab account and $REPO with the repository you want to work on.

Tip: To update your old fork, see rebasing.

Cloning aports repository

If you want to clone the Alpine Linux aports repository, switch to the directory you want to have the aports/ directory in and launch git. Unless you have necessary Developer permissions, you will not be able to push your changes back to the repository.

git clone git://git.alpinelinux.org/aports.git

Tip: If you are using proxy server:

git clone https://git.alpinelinux.org/aports

If you want only the last 3 revisions:

git clone git://git.alpinelinux.org/aports.git --depth 3

Use the command below to see the full log of the trunk.

git log

Stashing

git stash

if you want to "hide" your changes. Do this if you think there may be other commits against the same things you are working on and want to refresh your local checkout (using a git pull --rebase) from the master. Use git stash apply to get your stash back.

Reset your local repository

git checkout -f master

if you think your tree is pretty hopeless, need a kill-and-fill to bring the master into your local repository. You will lose local changes.

List the local branch

You can now list your local branch by doing

git branch

which should ouput

* master

List your local non committed changes

git status

Commit

Now you can start to work on your tree. As soon as you feel you have reached a step in development where you can commit your work locally, use

git commit -a

or

git commit <specific files>

or

git add <specific files> git commit

If you wish to give credit to someone else's work (e.g. you are applying a third party patch):

git commit <specific files> --author "Name Surname <user@example.com>

The format of the commit message should be:

One-line description that's less than 72 chars long
<second line empty>
Optional longer description with explanation why changes were made. Links to relevant issues
in Bugtracker can be done with:

  ref #<issuenumber>

It is also possible to resolve issues with:

  fixes #<issuenumber>

Think of first line as the subject in an email and the third line and on as the body of the email, describing what the commit does. You don't need the long description but the first line, the short description should be there as it will be showed in the commit log.

Tip: You can add the following line to your ~/.vimrc:

autocmd FileType gitcommit set textwidth=72

List your commits

To view the list your commits:

git log

To Check what you are going to push from local to remote:

git log origin..master

Keeping your local working branch in sync

Pull the changes from upstream (git.alpinelinux.org)

git pull --rebase

Tip: You can tell git to use rebase, rather than merge (means that '--rebase' would automatically be issued at 'git pull').
Run the command:

git config branch.origin.rebase true

Next time you do 'git pull' you are actually doing a 'git pull --rebase'.

Git Tag

Create an annotated tag and push it.

git tag -a tagname -m 'commit message (e.g release 1.x)' git push && git push --tags

Git push

To push your changes up to the master.

git push

Create a new project

Create your own directory that you want to become your new acf-mystuff project.

mkdir acf-mystuff cd acf-mystuff git init

Create your files and add/commit them to your git-project

git add ./ git commit

Rebasing against upstream master

It's best to always stay up-to-date with the state of the upstream Alpine Linux repository to ensure that no merge conflicts happen later on. To do that you first have to add a new git remote which points to the upstream repository (instead of your fork):

git remote add upstream https://gitlab.alpinelinux.org/alpine/$REPO

Now you can fetch all changes with:

git fetch --all

And then you can rebase with:

git rebase

Quality assurance

Before pushing anything to it is good to make sure that:

1. The package actually builds
2. Commit message is good
3. pkgrel is bumped if needed
4. no whitespace damage (last chars of a line is whitespace)

The following git hook will help you catch some common errors early:

#!/bin/sh

# Redirect output to stderr.
exec 1>&2

git diff --cached --name-only HEAD | grep 'APKBUILD$' | while read f; do
        olddir=$PWD
        cd ${f%/APKBUILD}
        if ! abuild sanitycheck && verify; then
                exit 1
        fi
        cd "$olddir"
done

# If there are whitespace errors, print the offending file names and fail.
exec git diff-index --check --cached HEAD --

Install it as .git/hooks/pre-commit and make it executable.

Further reading

• Git Tutorial
• Git - SVN Crash Course (quickstart if you know svn)
• A tour of git: the basics Recommended
• The Git Community Book
• Git From the Bottom Up
• Very good Git guide

See also

• Submit new packages
• Creating an Alpine package
• Package Maintainers
• Developer repositories
• Using Cgit
• Gitolite