Development using git: Difference between revisions

From Alpine Linux
(removed the svn migration stuff to separate doc)
(renewed the doc a bit. removed the create new repo part)
Line 1: Line 1:
[http://git.or.cz Git] is now being used for version control of the [http://dev.alpinelinux.org/cgit/cgit.cgi/alpine-baselayout/ alpine-baselayout] and [http://dev.alpinelinux.org/cgit/cgit.cgi/alpine-conf alpine-conf] packages.  
This document describes how to use [http://git-scm.com git] for Alpine Linux development and related projects.


== Configuring git ==
= 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.
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"
{{Cmd|<nowiki>git config --global user.name "Your Name Comes Here"
git config --global user.email you@yourdomain.example.com
git config --global user.email you@yourdomain.example.com</nowiki>}}


== Git Clone ==
{{Tip| If you want to use git with colored output use:
  {{Cmd|git config --global color.ui true}}
}}


To get started, clone the [http://dev.alpinelinux.org/cgit git repository] for the package you are interested in:


  git clone git://git.alpinelinux.org/alpine-baselayout
== Cloning the repository via Git ==
  git clone git://git.alpinelinux.org/alpine-conf
{{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.


Make your changes.  
If you want only the last 3 revisions:
{{Cmd|git clone git://git.alpinelinux.org/aports.git --depth 3}}


To prepare a patch:
{{Cmd|git log}}
to see the full log of the trunk.


git diff &gt; short-description-of-change.patch
You can also browse the git repository via [http://git.alpinelinux.org/cgit/aports cgit].


This diff can be sent to [mailto:alpine-devel@lists.alpinelinux.org alpine-devel@lists.alpinelinux.org] mailing list.


== Create new git repository for a new project ==
== General GIT Workflow ==
Start with creating a new directory. In this example the project will be named myproj.
# 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]])


  mkdir myproj
{{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.
cd myproj


Lets initialize the git repository. This will create the .git dir.
{{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.
git init


Now create the initial files you want. In this example we just create hello.txt
== List the local branch ==
  echo "hello git" > hello.txt
You can now list your local branch by doing
{{Cmd|git branch}}
which should ouput
  * master


We add this to the git "index" and commit it. The -v option shows the diff as a last reiew. Your $EDITOR will be opened and you will need to create a description of the initial commit.
== List your local non committed changes ==
git add hello.txt
  {{Cmd|git status}}
  git commit -v


The format of the commit message should be:
== Commit ==
  [first line]One-line descrption thats les than 72 chars long
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
  [second line empty]
  {{Cmd|git commit -a}}
  [third line]longer description.
or
  {{Cmd|git commit <specific files>}}
or
  {{Cmd|git add <specific files>
git commit}}


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.
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>}}


Now you can see the initial commit with:
The format of the commit message should be:
  git log
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>


Make some more changes. In this example we just append some text to hello.txt
echo "hello again" >> hello.txt


To check what you have done since last commit use:
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.
git log


To commit the change do:
== List your commits ==
  git add hello.txt
  {{Cmd|git log}}
git commit -v


or alternatively:
git commit -a -v


The separate ''git add'' is useful when you ave changed many files but just want commit some of the changed files.
== Keeping your local working branch in sync ==
Pull the changes from upstream (git.alpinelinux.org)
{{Cmd|git pull --rebase}}


== Publish the new repo to git.alpinelinux.org ==
== Submitting patches to the alpine-devel mailing list ==
make a 'bare' copy of your git repository.
cd ..
git clone --bare myproj myrepo.git


Copy that to git.alpinelinux.org. You need an ssh account for this.
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:
scp -r myproj.git git.alpinelinux.org:
{{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.


Send an email to Natanael Copa (or ping him on irc) to make a symlink of it to /gitroot on and to make it visible from cgit.
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.


Now you can clone the remote repository from git.alpinelinux.org. First you have to remove the old ''myproj'' directory. Then you clone it with ssh.
<!-- what does the following mean? -->
mv myproj myproj.backup
Don't do:
git clone ssh://git.alpinelinux.org/~/myproj.git
* [PATCH 0/m]
** [PATCH 1/m]
*** [PATCH 2/m]
**** ...
But do:
* [PATCH 0/m]
** [PATCH 1/m]
** [PATCH 2/m]
** ..


Now you have a local copy of the remote repository in ''myproj/'' directory. You can make changes there as much as you want. You can make commits, tags, undo/redo commits/tags (thats not pushed). You can do that without even having internet access. When you want to submit your changes (all you commits since last ''pull'') you do:
git push
== References  ==
If you are a developer with ssh access (with permissions) you might want to take a look at these docs:
*[[Development_using_git_with_write_access]]


= Documentation about git =
Some other useful documents  
Some other useful documents  
 
*[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://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://cworth.org/hgbook-git/tour/ A tour of git: the basics] '''Recommended'''  
*[http://book.git-scm.com/ The Git Community Book]
*[http://book.git-scm.com/ The Git Community Book]
* [http://wiki.sourcemage.org/Git_Guide Very good Git guide]
[[Category:Development]]

Revision as of 09:47, 6 August 2010

This document describes how to use git for Alpine Linux development and related projects.

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

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

git config --global color.ui true


Cloning the repository via Git

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:

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

git log

to see the full log of the trunk.

You can also browse the git repository via cgit.


General GIT Workflow

  1. Make your file edits in your local checkout of the local copy of repository.
  2. git commit the changes in your local repository
  3. git pull --rebase to bring the rest of your local repository up to date
  4. git log origin..master to check what you are going to commit
  5. 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)

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.

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 developement 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 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>


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.

List your commits

git log


Keeping your local working branch in sync

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

git pull --rebase

Submitting patches to the alpine-devel mailing list

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:

rm -Rf patches git format-patch -o patches origin git send-email --to alpine-devel@lists.alpinelinux.org patches

This requires that you have installed the git-perl package.

If you have multiple patch consider using:

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.

Don't do:

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

But do:

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


Documentation about git

Some other useful documents

Retrieved from "https://wiki.alpinelinux.org/w/index.php?title=Development_using_git&oldid=4211"