Git: Difference between revisions

From Alpine Linux
(renewed the doc a bit. removed the create new repo part)
m (rephrased the sentence)
 
(50 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 i.e to [[#Submitting Patches|submit patches]] or to submit [[Creating_an_Alpine_package|new packages]] that you've created. If you just want to browse the Alpine [[Development_using_git:Developer_repositories|Developer repositories]], please visit [https://git.alpinelinux.org/aports git.alpinelinux.org].  If you are new to git and need quick reference, check [[#Git Basics|Git Basics]] and also refer [[#Further reading|further reading]] section.


= Basic Git usage =
== General GIT Workflow ==
# [[#Configure your global git config|Configure]] your git
# [[#Cloning a repository via Git|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|Quality assurance]]
# Commit the changes in your local repository: {{Cmd|git commit}}
# Bring the rest of your local repository up to date: {{Cmd|git pull --rebase}}
# Check what you are going to push: {{Cmd|git log origin..master}}
# If you have write access Move your changes up to the master  {{Cmd|git push}}
# If you do not have write access, you can [[#Submitting Patches|submit patches]] .


== Configure your global git config ==
{{:Development_using_git:Configuration}}
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"
git config --global user.email you@yourdomain.example.com</nowiki>}}


{{Tip| If you want to use git with colored output use:
{{Tip| If you want to use git with colored output use:
  {{Cmd|git config --global color.ui true}}
  {{Cmd|git config --global color.ui true
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>}}
}}


== Cloning the repository via Git ==
== Cloning a repository via Git ==
{{Cmd|git clone git://git.alpinelinux.org/aports.git}}
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.


If you want only the last 3 revisions:
There are two ways to work with the Alpine git repository...
{{Cmd|git clone git://git.alpinelinux.org/aports.git --depth 3}}


{{Cmd|git log}}
* [[#Without write access|Without write access]]
to see the full log of the trunk.
* [[#with write access|with write access]]


You can also browse the git repository via [http://git.alpinelinux.org/cgit/aports cgit].
=== Without write access ===


If you want to clone the Alpine aports repository, switch to the directory you want to have the ''aports/'' directory in and launch git.
{{Cmd|git clone <nowiki>git://git.alpinelinux.org/aports.git</nowiki>}}


== General GIT Workflow ==
{{Tip| If you are using proxy server:
# Make your file edits in your local checkout of the local copy of repository.
{{Cmd|git clone https://git.alpinelinux.org/aports}}
# ''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.
If you want only the last 3 revisions:


{{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.
{{Cmd|git clone <nowiki>git://git.alpinelinux.org/aports.git</nowiki> --depth 3}}


== List the local branch ==
Use the command below to see the full log of the trunk.
You can now list your local branch by doing
{{Cmd|git branch}}
which should ouput
* master


== List your local non committed changes ==
{{Cmd|git log}}
{{Cmd|git status}}


== Commit ==
=== With write access ===
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):
{{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>


If you have write access to the Alpine repository, the URL needs to be adjusted for cloning a repository


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.
{{Cmd|git clone git@git.alpinelinux.org:aports}}


== List your commits ==
Alternatively you can set the remote url of an exisiting git clone:
{{Cmd|git log}}
{{Cmd|git remote set-url origin git@git.alpinelinux.org:aports}}




== Keeping your local working branch in sync ==
== Quality assurance ==
Pull the changes from upstream (git.alpinelinux.org)
{{:Development using git:Quality assurance}}
{{Cmd|git pull --rebase}}


== Submitting patches to the alpine-devel mailing list ==
== Submitting Patches ==


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:
{{:Development_using_git:Creating_patches}}
{{Cmd|<nowiki>rm -Rf patches
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:
{{Cmd|git send-email --compose --no-chain-reply-to --to alpine-devel@lists.alpinelinux.org patches}}
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? -->
== Git Basics ==
Don't do:
{{:Include:Git Basics|}}
* [PATCH 0/m]
** [PATCH 1/m]
*** [PATCH 2/m]
**** ...
But do:
* [PATCH 0/m]
** [PATCH 1/m]
** [PATCH 2/m]
** ..


== Other Related articles ==
* [[Creating_an_Alpine_package|Submit new packages]]
* [[Package Maintainers]]
* [[Development_using_git:Developer_repositories|Developer repositories]]
* [[Development_using_git:Cgit| Using Cgit]]
* [[Gitolite]]


= Documentation about git =
== Further reading ==
Some other useful documents
{{:Development_using_git:Documentation}}
*[http://www.kernel.org/pub/software/scm/git/docs/tutorial.html Git Tutorial]
*[http://git.or.cz/course/svn.html Git - SVN Crash Course] (quickstart if you know svn)
*[http://cworth.org/hgbook-git/tour/ A tour of git: the basics] '''Recommended'''
*[http://book.git-scm.com/ The Git Community Book]
* [http://wiki.sourcemage.org/Git_Guide Very good Git guide]


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

Latest revision as of 12:10, 14 August 2024

This document describes how to use git for Alpine Linux development i.e to submit patches or to submit new packages that you've created. If you just want to browse the Alpine Developer repositories, please visit git.alpinelinux.org. If you are new to git and need quick reference, check Git Basics and also refer further reading section.

General GIT Workflow

  1. Configure your git
  2. Clone the alpine Git repository
  3. Make your file edits in your local checkout of the local copy of repository.
  4. Ensure that your commits meets the Quality assurance
  5. Commit the changes in your local repository:

    git commit

  6. Bring the rest of your local repository up to date:

    git pull --rebase

  7. Check what you are going to push:

    git log origin..master

  8. If you have write access Move your changes up to the master

    git push

  9. If you do not have write access, you can submit patches .

Configure your global git config

First you need to tell your name and email to git. This name and email will show up in all your commits.

git config --global user.name "Your Name Comes Here" git config --global user.email you@yourdomain.example.com

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

Cloning a repository via Git

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

Without write access

If you want to clone the Alpine aports repository, switch to the directory you want to have the aports/ directory in and launch git.

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

With write access

If you have write access to the Alpine repository, the URL needs to be adjusted for cloning a repository

git clone git@git.alpinelinux.org:aports

Alternatively you can set the remote url of an exisiting git clone:

git remote set-url origin git@git.alpinelinux.org:aports


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.

Submitting Patches

New aports should normally go into testing repository. After a reasonable testing period if the package is complete (e.g. it has an init script, it has a working and sane default configuration, etc.) and it has a maintainer it can be moved into community repository. Main repository is for packages that are either core of the linux system or are dependencies of other core packages. A package in main cannot have a dependency in community or testing and a package in community cannot have a dependency on packages in testing.

There are currently two ways to contribute to propose changes, via Gitlab and via the mailing list.

Submitting patches via Gitlab

Setup

To submit patches on Alpine Linux' Gitlab instance you first have to create an account for it here. It's recommended to set a SSH key now, refer to the Gitlab docs for how to do that.

Creating a merge request

Now that you're all setup you have to fork the repository you want to contribute to, for example if you want to open a merge request for aports you would have to fork alpine/aports, see the Gitlab docs if you're having problems with that. Other repositories belonging to Alpine Linux live in the Alpine organisation. If you already have an old fork, first clone it and then update it as shown below.

After forking you can clone the repository like so:

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. Now you can change to another branch (e.g. the name of the package you want to edit) with:

(If necessary, update an old fork first, see rebasing, below)

git checkout -b pkgname

Do your changes now and then push with:

git push -u origin $branchname

Gitlab will print an URL to create a merge request in your terminal.

Amending changes to a merge request

If reviewers requested changes or if you noticed that something should be changed about your merge request's change you can simply amend your changes to the right commit and force push. So if you want to change the commit at the tip of your branch you can simply do:

git commit --amend

If you want to change a commit that's not at the tip of your branch you can do:

git commit --fixup $SHA1_OF_COMMIT_YOU_WANT_TO_FIX

Afterwards you have to force-push in order to update your merge request:

git push -f origin

Rebasing against Alpine Linux's 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

Submitting patches via the mailing list

Warning: Submitting patches via the mailing list is currently broken as-of 15 August 2023


Patches should be created with git and submitted to alpine-aports mailing list with git send-email (which needs the git-email Alpine package).

Only the last commit with 'git send-email'

To submit the last commit as a patch to alpine-aports mailing list:

git send-email --to alpine-aports@lists.alpinelinux.org -1

Tip: You save the To-address (does not require '--to alpine-aports@lists.alpinelinux.org') in the git config with:

git config sendemail.to alpine-aports@lists.alpinelinux.org

The first line in commit message will be subject and the long description (separated with empty line) will be the body in the email. The example below shows

testing/packagename: new aport <- header

https://example.com/packagename <- body
wonderful package
Note: The git send-email command is provided by the git-email package (git-perl in v2.7 and older).

See Development using git#Email_configuration on how configure SMTP Auth.

Multiple commits with 'git send-email'

If you have many commits you can create a directory with patches and send them with git send-email.

rm -Rf patches mkdir patches git format-patch -o patches origin git send-email patches --compose --no-chain-reply-to --to alpine-aports@lists.alpinelinux.org

You can also format patches for the last x number of commits with:

git format-patch -x -o patches

This will produce the patches for each local commit in the directory "patches" and send them. Use --no-chain-reply-to to avoid that each patch is sent as a reply to the previous patch.

Eg.

  • [PATCH 0/m]
    • [PATCH 1/m]
      • [PATCH 2/m]
        • ...

With the option --no-chain-reply-to the patches will be sent as a reply to the first email, the cover letter (the [PATCH 0/m]) and will make the email thread nicer. Like this:

  • [PATCH 0/m]
    • [PATCH 1/m]
    • [PATCH 2/m]
    • ..

Resend an updated patch

Sometimes patches are rejected due to minor issues in the patch. Do not send an incremental patch on top of your initial, bad, patch. Instead, recreate the patch and send a new, fixed version of your patch. (use git commit --amend to edit a local commit).

When you sending a second version of the patch use --subject-prefix "PATCH v2" to indicate that this is a new version of a previously sent patch. You may also use --in-reply-to <message-id> where <message-id> the the id of email requesting the resend.

You should also write a note on the what was changed. Use --annotate for this and write the comment under the three dashes "---" so the note is not included in the commit message. For example:

...
Subject: [PATCH v2] testing/mypackage: new aport

https://example.com
Example package
---
Changes v1 -> v2:
 - removed depends
 - added zlib-dev to makedepends

 testing/mypackage/APKBUILD | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)
 create mode 100644 testing/mypackage/APKBUILD
...

Note that the notes that are below the "---" will not be included in the commit message.


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.

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

git log


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

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

Other Related articles

Further reading