Git: Difference between revisions

From Alpine Linux
(renewed the doc a bit. removed the create new repo part)
(moved content from Aports tree page)
 
(67 intermediate revisions by 14 users not shown)
Line 1: Line 1:
This document describes how to use [http://git-scm.com git] for Alpine Linux development and related projects.
This document describes how to use [https://git-scm.com git] for Alpine Linux development. If you just want to browse all the available Alpine git repositories, [https://git.alpinelinux.org git.alpinelinux.org] shows them all.


= Basic Git usage =
If you are new to git and need quick reference, check [[#Git Basics|Git Basics]]. For more info, refer [[#Further reading|further reading]] section.


== Configure your global git config ==
== General git workflow ==
First you need to tell your name and email to git. This name and email will show up in all your commits.


{{Cmd|<nowiki>git config --global user.name "Your Name Comes Here"
There are two ways to work with the Alpine git repository.  
git config --global user.email you@yourdomain.example.com</nowiki>}}
* without write access.
* with write access.


{{Tip| If you want to use git with colored output use:
Most contributors to Alpine linux will be working [[#Forking a repository|with a forked repository]]. Only [https://docs.alpinelinux.org/governance/0.1b/Teams/developers.html Alpine Developers] have write access.  
{{Cmd|git config --global color.ui true}}
}}


Follow this [[Creating_an_Alpine_package#Overview|overview]] to [[Creating an Alpine package|create a package]] or [[Creating patches|submit a patch]] even without write access.


== Cloning the repository via Git ==
=== Configure your global git config ===
{{:Include:Git configuration}}
{{Cmd|git clone git://git.alpinelinux.org/aports.git}}
If you want to use git with colored output use:{{Cmd|git config --global color.ui true
The full aports repository is now copied to your ''aports/.git'' dir and the latest commit is checked out in ''aports/''. Most operations you do from here will happen on your local copy and will not affect git.alpinelinux.org.
git config --global core.pager more}}
{{Tip|If you want to use git with proxy server:{{Cmd|git config --global http.proxy <nowiki>http://proxy_ip:proxy_port</nowiki>}}}}


If you want only the last 3 revisions:
=== Setup gitlab account ===
{{Cmd|git clone git://git.alpinelinux.org/aports.git --depth 3}}


{{Cmd|git log}}
Follow the below instructions to setup an account in the [https://gitlab.alpinelinux.org Alpine Linux' Gitlab instance].  
to see the full log of the trunk.


You can also browse the git repository via [http://git.alpinelinux.org/cgit/aports cgit].
* Create an account at https://gitlab.alpinelinux.org/users/sign_in.
* It's recommended to set a SSH key now, refer to the [https://docs.gitlab.com/user/ssh/ Gitlab docs] for how to do that.


=== Forking a repository ===


== General GIT Workflow ==
To [[Creating an Alpine package|create an Alpine package]] or [[Creating patches|submit a patch]] without write access to the Alpine repository, you need to fork the desired repository. [[#Setup gitlab account|Setup gitlab account]], if not already done.
# Make your file edits in your local checkout of the local copy of repository.
# ''git commit''      the changes in your local repository
# ''git pull --rebase''  to bring the rest of your local repository up to date
# ''git log origin..master'' to check what you are going to commit
# ''git push''    to move your changes up to the master. This requires you have an ssh login and have cloned via ssh://git.alpinelinux.org and not via git://git.alpinelinux.org. (see [[Development using git with write access]])


{{Cmd|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.  
For packages, create a fork for '''aports''' at https://gitlab.alpinelinux.org/alpine/aports. Refer [https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html#creating-a-fork Gitlab docs] if you're having problems with that.  


{{Cmd|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.
If you want to contribute to other repositories belonging to Alpine Linux, they live in the [https://gitlab.alpinelinux.org/alpine Alpine organisation] and you may want to fork them as above.  


== List the local branch ==
Once created, the fork resides on the Gitlab server, until you [[#Cloning your forked repository|clone your fork]].
You can now list your local branch by doing
{{Cmd|git branch}}
which should ouput
* master


== List your local non committed changes ==
=== Cloning your forked repository ===
  {{Cmd|git status}}
   
 
By cloning the aports from the server, you are fetching the APKBUILD files along with other build-related files for each Alpine package from the [[Aports tree|aports tree]] to your local build environment. You can clone your [[#Forking a repository|forked]] repository, by replacing $USER with the nickname of your Gitlab account and $REPO in the git command: {{Cmd|$ git clone <nowiki>git@gitlab.alpinelinux.org:$USER/$REPO.git</nowiki>}}
== Commit ==
Now you can start to work on your tree. As soon as you feel you have reached a step in developement where you can commit your work '''locally''', use
{{Cmd|git commit -a}}
or
{{Cmd|git commit <specific files>}}
or
{{Cmd|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):
Before you clone the '''aports''' repository, switch to the directory you want to have the {{Path|aports/}} directory. To clone aports into {{Path|~/src/aports}} or {{Path|~/aports}}, issue the commands {{ic|$ cd ~/src/}} or {{ic|$ cd ~/}} respectively.
{{Cmd|git commit <specific files> --author "Name Surname <user@example.com>}}
 
The format of the commit message should be:
One-line descrption thats 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>


To clone your [[#Forking a repository|forked]] '''aports''' repository with only the last 3 revisions, replace $USER and issue the command: {{Cmd|$ git clone <nowiki>git@gitlab.alpinelinux.org:$USER/aports.git</nowiki> --depth 3}}


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 dont need the long description but the first line, the short description should be there as it will be showed in the commit log.
To see the full log of the trunk, use the command below: {{Cmd|git log}}


== List your commits ==
{{Tip|To update your old clone, see [[Include:Git_Basics#Rebasing_against_upstream_master|rebasing]].}}
{{Cmd|git log}}


=== Cloning aports repository ===


== Keeping your local working branch in sync ==
You can also clone the Alpine Linux aports repository instead of [[#Cloning your forked repository|forked repository]] using the command: {{Cmd|$ git clone <nowiki>git://git.alpinelinux.org/aports.git</nowiki>}}  
Pull the changes from upstream (git.alpinelinux.org)
{{Cmd|git pull --rebase}}


== Submitting patches to the alpine-devel mailing list ==
Unless you have necessary permissions, you will not be able to push your changes back to the repository.


If you have been developing on Alpine Linux locally and (still) don't have write access, you can submit all your commits in one shot using:
== Git Basics ==
{{Cmd|<nowiki>rm -Rf patches
{{:Include:Git Basics}}
git format-patch -o patches origin
git send-email --to alpine-devel@lists.alpinelinux.org patches</nowiki>}}
This requires that you have installed the '''git-perl''' package.


If you have multiple patch consider using:
== Quality assurance ==
{{Cmd|git send-email --compose --no-chain-reply-to --to alpine-devel@lists.alpinelinux.org patches}}
{{:Development using git:Quality assurance}}
This will produce the patches for each local commit in the directory "patches" and send them.
Use --no-chain-reply-to make sure it doesn't reply.


<!-- what does the following mean? -->
== Further reading ==
Don't do:
{{:Development_using_git:Documentation}}
* [PATCH 0/m]
** [PATCH 1/m]
*** [PATCH 2/m]
**** ...
But do:
* [PATCH 0/m]
** [PATCH 1/m]
** [PATCH 2/m]
** ..


== See also ==


= Documentation about git =
* [[Creating_an_Alpine_package|Submit new packages]]
Some other useful documents
* [[Creating an Alpine package]]
*[http://www.kernel.org/pub/software/scm/git/docs/tutorial.html Git Tutorial]
* [[Package Maintainers]]
*[http://git.or.cz/course/svn.html Git - SVN Crash Course] (quickstart if you know svn)
* [[Development_using_git:Developer_repositories|Developer repositories]]
*[http://cworth.org/hgbook-git/tour/ A tour of git: the basics] '''Recommended'''
* [[Development_using_git:Cgit| Using Cgit]]
*[http://book.git-scm.com/ The Git Community Book]
* [[Gitolite]]
* [http://wiki.sourcemage.org/Git_Guide Very good Git guide]


[[Category:Development]]
[[Category:Development]]
[[Category:Git]]

Latest revision as of 05:15, 6 October 2025

This document describes how to use git for Alpine Linux development. If you just want to browse all the available Alpine git repositories, git.alpinelinux.org shows them all.

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

General git workflow

There are two ways to work with the Alpine git repository.

  • without write access.
  • with write access.

Most contributors to Alpine linux will be working with a forked repository. Only Alpine Developers have write access.

Follow this overview to create a package or submit a patch even without write access.

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 Name" $ git config --global user.email "your@email.address"

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

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

Setup gitlab account

Follow the below instructions to setup an account in the Alpine Linux' Gitlab instance.

Forking a repository

To create an Alpine package or submit a patch without write access to the Alpine repository, you need to fork the desired repository. Setup gitlab account, if not already done.

For packages, create a fork for aports at https://gitlab.alpinelinux.org/alpine/aports. Refer Gitlab docs if you're having problems with that.

If you want to contribute to other repositories belonging to Alpine Linux, they live in the Alpine organisation and you may want to fork them as above.

Once created, the fork resides on the Gitlab server, until you clone your fork.

Cloning your forked repository

By cloning the aports from the server, you are fetching the APKBUILD files along with other build-related files for each Alpine package from the aports tree to your local build environment. You can clone your forked repository, by replacing $USER with the nickname of your Gitlab account and $REPO in the git command:

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

Before you clone the aports repository, switch to the directory you want to have the aports/ directory. To clone aports into ~/src/aports or ~/aports, issue the commands $ cd ~/src/ or $ cd ~/ respectively.

To clone your forked aports repository with only the last 3 revisions, replace $USER and issue the command:

$ git clone git@gitlab.alpinelinux.org:$USER/aports.git --depth 3

To see the full log of the trunk, use the command below:

git log

Tip: To update your old clone, see rebasing.

Cloning aports repository

You can also clone the Alpine Linux aports repository instead of forked repository using the command:

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

Unless you have necessary permissions, you will not be able to push your changes back to the repository.

Git Basics

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.

Change to another branch

To create and change to another branch:

git checkout -b branchname

So to change to another branch (e.g. the name of the package you want to edit) with:

git checkout -b pkgname

Tip: If you have an old fork, update the fork first, see rebasing

To change from one branch to another existing branch:

git checkout branchname

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

See also