Development using git: Difference between revisions

From Alpine Linux
(add info on smtp server for git-send email and gmail example)
No edit summary
 
(36 intermediate revisions by 13 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.
{{Move|Git|All git development articles should be consolidated}}


= Basic Git usage =
This document describes how to use [https://git-scm.com git] for Alpine Linux development and related projects. If you just want to browse the Alpine git repositories, please visit [https://git.alpinelinux.org/aports git.alpinelinux.org].


== Configure your global git config ==
== Basic Git usage ==
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"
{{:Development_using_git:Configuration}}
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}}
}}
}}


To be able send your commits (pathces) via email you need configure an SMTP server.
{{Tip| If you want to use git with proxy server:
{{Cmd|git config --global sendemail.smtpserver smtp.exmaple.com}}
{{Cmd|git config --global http.proxy <nowiki>http://proxy_ip:proxy_port</nowiki>}}
}}


For sending from a gmail address you can do:
== Cloning a repository via Git ==
{{Cmd|<nowiki>git config --global sendemail.smtpserver smtp.gmail.com
git config --global sendemail.smtpserverport 587
git config --global sendemail.smtpencryption tls
git config --global sendemail.smtpuser your_email@gmail.com</nowiki>}}


Optionally, it is possible to skip the password prompt by adding it to the configuration with:
There are two ways to work with the Alpine git repository...
{{Cmd|git config --global sendemail.smtppass your_password}}


== Cloning the repository via Git ==
* ...without write access.
* ...with write access.
{{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:
[https://git.alpinelinux.org/aports git.alpinelinux.org] shows all available Alpine git repositories.
{{Cmd|git clone git://git.alpinelinux.org/aports.git --depth 3}}


{{Cmd|git log}}
=== Without write access ===
to see the full log of the trunk.


You can also browse the git repository via [http://git.alpinelinux.org/cgit/aports cgit].
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>}}


{{Tip| If you are using proxy server:
{{Cmd|git clone https://git.alpinelinux.org/aports}}
}}


== General GIT Workflow ==
If you want only the last 3 revisions:
# 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.
{{Cmd|git clone <nowiki>git://git.alpinelinux.org/aports.git</nowiki> --depth 3}}


{{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.
Use the command below to see the full log of the trunk.  


== List the local branch ==
{{Cmd|git log}}
You can now list your local branch by doing
{{Cmd|git branch}}
which should ouput
* master


== List your local non committed changes ==
=== Submitting work without write access ===
{{Cmd|git status}}


== Commit ==
You can still [https://wiki.alpinelinux.org/wiki/Creating_patches submit a patch] without write access to the Alpine repository. For this you need to create an account on Alpine's GitLab, fork the desired repository (the fork resides on the server), clone the fork on your computer, make your changes into a separate branch, push the squashed branch to the fork (as branch; do not merge/rebase it into the master!) and create a merge request for that branch through the GitLab Web GUI.
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):
=== With write access ===
{{Cmd|git commit <specific files> --author "Name Surname <user@example.com>}}


The format of the commit message should be:
If you have write access to the Alpine repository, the URL needs to be adjusted for cloning a repository
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>


{{Cmd|git clone git@git.alpinelinux.org:aports}}


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.
Alternatively you can set the remote url of an exisiting git clone:
{{Cmd|git remote set-url origin git@git.alpinelinux.org:aports}}


== List your commits ==
== General GIT Workflow ==
{{Cmd|git log}}
# Make your file edits in your local checkout of the local copy of repository.
 
# Commit the changes in your local repository: {{Cmd|git commit}}
 
# Bring the rest of your local repository up to date: {{Cmd|git pull --rebase}}
== Keeping your local working branch in sync ==
# Check what you are going to push: {{Cmd|git log origin..master}}
Pull the changes from upstream (git.alpinelinux.org)
# Move your changes up to the master if you have write access {{Cmd|git push}} or [[Creating_patches|create a patch]] if not.
{{Cmd|git pull --rebase}}
 
== Submitting patches to the alpine-devel mailing list ==
To submit the last commit as a patch to alpine-devel mailing list:
{{Cmd|git send-email --to alpine-devel@lists.alpinelinux.org HEAD^}}
The first line in commit message will be ''subject'' and the long description (separated with empty line) will be the body in the email.
 
{{Note|The git send-email command is provided by the '''git-perl''' package}}
 
If you have many commits you can create a dir with patches and send them with git send-email.
{{Cmd|<nowiki>rm -Rf patches
git format-patch -o patches origin
git send-email --to alpine-devel@lists.alpinelinux.org patches</nowiki>}}


If you have multiple patch consider using:
== Other related articles ==
{{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? -->
* [[Development_using_git:Basic_usage| Basic usage]]
Don't do:
* [[Package Maintainers]]
* [PATCH 0/m]
* [[Creating patches]]
** [PATCH 1/m]
* [[Development_using_git:Developer_repositories|Developer repositories]]
*** [PATCH 2/m]
* [[Development_using_git:Cgit| Using Cgit]]
**** ...
* [[Development using git:Quality assurance]]
But do:
* [[Gitolite]]
* [PATCH 0/m]
** [PATCH 1/m]
** [PATCH 2/m]
** ..


= 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 06:47, 23 August 2023

This page is proposed for moving ...

It should be renamed to Git. All git development articles should be consolidated (Discuss)

This document describes how to use git for Alpine Linux development and related projects. If you just want to browse the Alpine git repositories, please visit git.alpinelinux.org.

Basic Git usage

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.
  • ...with write access.

git.alpinelinux.org shows all available Alpine git repositories.

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

Submitting work without write access

You can still submit a patch without write access to the Alpine repository. For this you need to create an account on Alpine's GitLab, fork the desired repository (the fork resides on the server), clone the fork on your computer, make your changes into a separate branch, push the squashed branch to the fork (as branch; do not merge/rebase it into the master!) and create a merge request for that branch through the GitLab Web GUI.

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

General GIT Workflow

  1. Make your file edits in your local checkout of the local copy of repository.
  2. Commit the changes in your local repository:

    git commit

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

    git pull --rebase

  4. Check what you are going to push:

    git log origin..master

  5. Move your changes up to the master if you have write access

    git push

    or create a patch if not.

Other related articles

Further reading