Using Git for Samba Development: Difference between revisions

From SambaWiki
(Using Git for Samba Development moved to Using Git-SVN for Samba4 Development: Official migration to Git is underway)
 
(New HOWTO for git development)
Line 1: Line 1:
#redirect [[Using Git-SVN for Samba4 Development]]
The previous pages based on the git-svn mirror can be found at [[Using Git-SVN for Samba4 Development]]



== Overview ==

Samba source code is now hosted in a shared git repository to
which all existing Samba Team members are allow to push to.
If you are a Team member and do not have an account on git.samba.org,
please email the team list and let the appropriate people know.

This shared repository has the same work flow as was used when
the SCM of choice was Subversion. In other words, you develop
in your local tree and push to the repo although is not not
necessary to push after every commit. This should be a familar
work flow for those who have used svk.



== Git Installation ==

The git source code is available from
http://www.kernel.org/pub/software/scm/git/.

The project home page is located at
http://git.or.cz/

You should probably familarize yourself with the Git tutorial at
http://www.kernel.org/pub/software/scm/git/docs/tutorial.html

The examples in the following sections are based off of the tools
and syntax used by git v1.5.3 or later which is the recommended
version for Samba. Either apt-get, yum, or make install the tools.
See Git documentation for details on this part.



== Basic Samba Git ==


The master git repository is located at git://git.samba.org/samba.git

There is also a GitWeb installation at http://gitweb.samba.org/

Step Zero is to set your name and email address for commits:

$ git config --global user.email Your.Email@domain.com
$ git config --global user.name "Your Real Name"

Next, clone the repository:

$ git-clone git://git.samba.org/samba.git samba
Initialized empty Git repository in /home/AD/gcarter/src/git/tmp/samba/.git/
remote: Generating pack...
remote: Done counting 440544 objects.
remote: Deltifying 440544 objects...
remote: 100% (440544/440544) done
Indexing 440544 objects...
remote: Total 440544 (delta 340808), reused 436199 (delta 336480)
100% (440544/440544) done
Resolving 340808 deltas...
100% (340808/340808) done
$ cd samba

List local and remote branches:
$ git-branch
* v3-2-stable

$ git-branch -r
origin/HEAD
origin/v2-2-stable
origin/v2-2-test
origin/v3-0-stable
origin/v3-0-test
origin/v3-2-stable
origin/v3-2-test
origin/v4-0-stable
origin/v4-0-test

Listing tags matching release-3-0-3*
$ git-tag -l release-3-0-3*
release-3-0-3
release-3-0-3pre1
release-3-0-3pre2
release-3-0-3rc1

Creating your own working branch from v3-2-test:
$ git-checkout -b my_branch origin/v3-2-test
Branch my_branch set up to track remote branch refs/remotes/origin/v3-2-test.
Switched to a new branch "my_branch"

Do your own local work:
$ mkdir git-test
$ echo "hello" > git-test/README

View status of changes
$ git-status
# On branch my_branch
# Untracked files:
# (use "git add <file>..." to include in what will be committed)
#
# git-test/
nothing added to commit but untracked files present (use "git add" to track)

Add our new file to the local branch index:
$ git add git-test
$ git status
# On branch my_branch
# Changes to be committed:
# (use "git reset HEAD <file>..." to unstage)
#
# new file: git-test/README
#

Commit changes
$ git commit -m "Example file for HOWTO"
Created commit ad9a1eb: Example file for HOWTO
1 files changed, 1 insertions(+), 0 deletions(-)
create mode 100644 git-test/README

Do some more work and commit local changes....

Now fetch the remote branch history:
$ git-fetch

Merging remote branch changes:
$ git-merge origin/v3-2-test
Already up-to-date.

Push the changes to the shared repository
$ git push ssh://git.samba.org/data/git/jerry/draft2/samba.git my_branch:v3-2-test
updating 'refs/heads/v3-2-test' using 'refs/heads/my_branch'
from f2252e041e075e19bf27e53ab3ed62f39bc8b3e2
to ad9a1eb599c125964ac3e198d3003841edb4c54e
Generating pack...
Done counting 5 objects.
Result has 4 objects.
Deltifying 4 objects...
100% (4/4) done
Writing 4 objects...
100% (4/4) done
Total 4 (delta 1), reused 0 (delta 0)
refs/heads/v3-2-test: f2252e041e075e19bf27e53ab3ed62f39bc8b3e2 -> ad9a1eb599c125964ac3e198d3003841edb4c54e



== Explanation of Branches ==

The simplest way to explain the existing shared branches is to associate them with the previous SVN ones.

* The *-unstable tags point to the matching SAMBA_X_X branch (e.g. SAMBA_3_2 or SAMBA_4_0) at the time of the migration. These are now tags an not branches so you cannot push to them. Instead, your local work should be done in a local branch and pushed when completed. There is no need to push works-in-progress any longer unless you require some specific testing by the buildfarm.
* The *-test branches correspond to the release series dev branch (e.g. SAMBA_3_2_0). Anyone may check into these branches.
* The *-stable branches are used for release purposes similar tothe SAMBA_X_X_RELEASE branches in SVN. These are under the control of the currentl release manager for a given release series.


== FAQ ==

'''Q.''' How do I revert a commit?

'''A.''' The git-reset command allows you to reset the HEAD of the branch to any given point in history. To go back one commit, run "git-reset HEAD^". This will keep your local changes and you can make any additional changes before re-commiting the new work. Also see the "git-commit --amend" command and the "git-reset" man page for other examples.


'''Q.''' Is there a shorthand for git-push <URL> <local_repo:remote_repo>?

'''A.''' Yes. You can define a [remote "upstream"] section in your local repos .git/config file.

$ git-config remote.origin.url ssh://git.samba.org/data/git/samba.git
$ git-config remote.origin.push my_branch:v3-2-test
$ cat .git/config
...
[remote "origin"]
url = ssh://git.samba.org/data/git/jerry/draft2/samba.git
fetch = +refs/heads/*:refs/remotes/origin/*
push = my_branch:v3-2-test
[branch "my_branch"]
remote = origin
merge = refs/heads/v3-2-test


'''Q.''' How can I have access to the old CVS and SVN imported repositories via GIT without creating additional cloned repos?

'''A.''' You can add remote tracking repositories using git-remote:

$ git-remote add cvs git://git.samba.org/import/samba-cvsimport.git
$ git-fetch cvs
remote: Generating pack...
remote: Done counting 7070 objects.
Result has 5004 objects.
remote: Deltifying 5004 objects...
remote: 100% (5004/5004) done
Indexing 5004 objects...
remote: Total 5004 (delta 3836), reused 4098 (delta 3044)
100% (5004/5004) done
Resolving 3836 deltas...
100% (3836/3836) done
461 objects were added to complete this thin pack.
* refs/remotes/cvs/APPLIANCE_HEAD: storing branch 'APPLIANCE_HEAD' of git:// git.samba.org/import/samba-cvsimport
commit: af0e201

You can then see the remote branches using "git-branch -r" and work with them in the same way you did for the "origin" branches obtained in the initial git-clone.

Revision as of 17:45, 9 October 2007

The previous pages based on the git-svn mirror can be found at Using Git-SVN for Samba4 Development


Overview

Samba source code is now hosted in a shared git repository to which all existing Samba Team members are allow to push to. If you are a Team member and do not have an account on git.samba.org, please email the team list and let the appropriate people know.

This shared repository has the same work flow as was used when the SCM of choice was Subversion. In other words, you develop in your local tree and push to the repo although is not not necessary to push after every commit. This should be a familar work flow for those who have used svk.


Git Installation

The git source code is available from

 http://www.kernel.org/pub/software/scm/git/.

The project home page is located at

 http://git.or.cz/

You should probably familarize yourself with the Git tutorial at

 http://www.kernel.org/pub/software/scm/git/docs/tutorial.html

The examples in the following sections are based off of the tools and syntax used by git v1.5.3 or later which is the recommended version for Samba. Either apt-get, yum, or make install the tools. See Git documentation for details on this part.


Basic Samba Git

The master git repository is located at git://git.samba.org/samba.git

There is also a GitWeb installation at http://gitweb.samba.org/

Step Zero is to set your name and email address for commits:

 $ git config --global user.email Your.Email@domain.com
 $ git config --global user.name "Your Real Name"

Next, clone the repository:

 $ git-clone git://git.samba.org/samba.git samba
 Initialized empty Git repository in /home/AD/gcarter/src/git/tmp/samba/.git/
 remote: Generating pack...
 remote: Done counting 440544 objects.
 remote: Deltifying 440544 objects...
 remote:  100% (440544/440544) done
 Indexing 440544 objects...
 remote: Total 440544 (delta 340808), reused 436199 (delta 336480)
  100% (440544/440544) done
 Resolving 340808 deltas...
  100% (340808/340808) done
 $ cd samba

List local and remote branches:

 $ git-branch
   * v3-2-stable
 $ git-branch -r
   origin/HEAD
   origin/v2-2-stable
   origin/v2-2-test
   origin/v3-0-stable
   origin/v3-0-test
   origin/v3-2-stable
   origin/v3-2-test
   origin/v4-0-stable
   origin/v4-0-test

Listing tags matching release-3-0-3*

 $ git-tag -l release-3-0-3*
 release-3-0-3
 release-3-0-3pre1
 release-3-0-3pre2
 release-3-0-3rc1

Creating your own working branch from v3-2-test:

 $ git-checkout -b my_branch origin/v3-2-test
 Branch my_branch set up to track remote branch refs/remotes/origin/v3-2-test.
 Switched to a new branch "my_branch"

Do your own local work:

 $ mkdir git-test
 $ echo "hello" > git-test/README

View status of changes

 $ git-status
 # On branch my_branch
 # Untracked files:
 #   (use "git add <file>..." to include in what will be committed)
 # 
 #       git-test/
 nothing added to commit but untracked files present (use "git add" to track)

Add our new file to the local branch index:

 $ git add git-test
 $ git status
 # On branch my_branch
 # Changes to be committed:
 #   (use "git reset HEAD <file>..." to unstage)
 #
 #       new file:   git-test/README
 #

Commit changes

 $ git commit -m "Example file for HOWTO"
 Created commit ad9a1eb: Example file for HOWTO
  1 files changed, 1 insertions(+), 0 deletions(-)
  create mode 100644 git-test/README

Do some more work and commit local changes....

Now fetch the remote branch history:

 $ git-fetch 

Merging remote branch changes:

 $ git-merge origin/v3-2-test
 Already up-to-date.

Push the changes to the shared repository

 $ git push ssh://git.samba.org/data/git/jerry/draft2/samba.git my_branch:v3-2-test
 updating 'refs/heads/v3-2-test' using 'refs/heads/my_branch'
   from f2252e041e075e19bf27e53ab3ed62f39bc8b3e2
   to   ad9a1eb599c125964ac3e198d3003841edb4c54e
 Generating pack...
 Done counting 5 objects.
 Result has 4 objects.
 Deltifying 4 objects...
  100% (4/4) done
 Writing 4 objects...
  100% (4/4) done
 Total 4 (delta 1), reused 0 (delta 0)
 refs/heads/v3-2-test: f2252e041e075e19bf27e53ab3ed62f39bc8b3e2 -> ad9a1eb599c125964ac3e198d3003841edb4c54e


Explanation of Branches

The simplest way to explain the existing shared branches is to associate them with the previous SVN ones.

  • The *-unstable tags point to the matching SAMBA_X_X branch (e.g. SAMBA_3_2 or SAMBA_4_0) at the time of the migration. These are now tags an not branches so you cannot push to them. Instead, your local work should be done in a local branch and pushed when completed. There is no need to push works-in-progress any longer unless you require some specific testing by the buildfarm.
  • The *-test branches correspond to the release series dev branch (e.g. SAMBA_3_2_0). Anyone may check into these branches.
  • The *-stable branches are used for release purposes similar tothe SAMBA_X_X_RELEASE branches in SVN. These are under the control of the currentl release manager for a given release series.


FAQ

Q. How do I revert a commit?

A. The git-reset command allows you to reset the HEAD of the branch to any given point in history. To go back one commit, run "git-reset HEAD^". This will keep your local changes and you can make any additional changes before re-commiting the new work. Also see the "git-commit --amend" command and the "git-reset" man page for other examples.


Q. Is there a shorthand for git-push <URL> <local_repo:remote_repo>?

A. Yes. You can define a [remote "upstream"] section in your local repos .git/config file.

 $ git-config remote.origin.url ssh://git.samba.org/data/git/samba.git
 $ git-config remote.origin.push my_branch:v3-2-test
 $ cat .git/config
 ...
 [remote "origin"]
         url = ssh://git.samba.org/data/git/jerry/draft2/samba.git
         fetch = +refs/heads/*:refs/remotes/origin/*
         push = my_branch:v3-2-test
 [branch "my_branch"]
         remote = origin
         merge = refs/heads/v3-2-test


Q. How can I have access to the old CVS and SVN imported repositories via GIT without creating additional cloned repos?

A. You can add remote tracking repositories using git-remote:

 $ git-remote add cvs git://git.samba.org/import/samba-cvsimport.git
 $ git-fetch cvs
 remote: Generating pack...
 remote: Done counting 7070 objects.
 Result has 5004 objects.
 remote: Deltifying 5004 objects...
 remote:  100% (5004/5004) done
 Indexing 5004 objects...
 remote: Total 5004 (delta 3836), reused 4098 (delta 3044)
  100% (5004/5004) done
 Resolving 3836 deltas...
  100% (3836/3836) done
 461 objects were added to complete this thin pack.
 * refs/remotes/cvs/APPLIANCE_HEAD: storing branch 'APPLIANCE_HEAD' of git://  git.samba.org/import/samba-cvsimport
   commit: af0e201

You can then see the remote branches using "git-branch -r" and work with them in the same way you did for the "origin" branches obtained in the initial git-clone.