Difference between revisions of "Using Git for Samba Development"

(explain our git workflow)
(redirect changed from Creating_Gitlab_Merge_Requests to creating a samba patch series)
(Tag: Redirect target changed)
 
(13 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
+
#REDIRECT [[Creating a Samba patch series]]
== Overview ==
 
 
 
Samba source code is now hosted in a shared git repository to which all existing Samba Team members are allow to push to after [[CodeReview|code review]] via the autobuild system.  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 is a shared repository, after review and via autobuild, all active development is in master as a series of rebased patches.  Samba's use of git is perhaps best described as the Centralised, rather than the Feature branch [https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow/ git workflow].
 
 
 
== Git Installation ==
 
 
 
* The git source code is available from [http://www.kernel.org/pub/software/scm/git/ http://www.kernel.org/pub/software/scm/git/].
 
* The project home page is located at [http://git.or.cz/ http://git.or.cz/].
 
* You should probably familiarize yourself with the [http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html Git tutorial].
 
 
 
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 [http://www.kernel.org/pub/software/scm/git/ Git documentation] for more details on this part.
 
 
 
If you are on OS X, both [http://macports.org/ MacPorts] and [http://finkproject.org/ Fink] contain working binary packages of Git. Building Git from source on OS X works fine, but resolving the chain of dependencies for asciidoc (which is needed to build the man pages) is very painful.
 
 
 
== GitHub ==
 
 
 
Many users may find it easier to start by [https://guides.github.com/activities/forking/ creating a fork] on [https://github.com GitHub].  Samba has a [https://github.com/samba-team/samba GitHub mirror] of the [https://git.samba.org/samba.git official git repository].
 
 
 
A [https://help.github.com/articles/using-pull-requests/ pull request] made against the [https://github.com/samba-team/samba Samba GitHub mirror] will trigger a mail to samba-technical with your patch.  Please ensure you have added [[CodeReview#commit_message_tags|Signed-off-by tags]] to your commits, and follow the [https://www.samba.org/samba/devel/copyright-policy.html Samba copyright policy]
 
 
 
== Basic Samba Git ==
 
 
 
 
 
The master git repository is located at ''git://git.samba.org/samba.git'' and ''https://git.samba.org/samba.git''.  There is also a [https://git.samba.org/ GitWeb installation].
 
 
 
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-test
 
 
 
  $ git branch -r
 
    origin/HEAD
 
    origin/v3-0-stable
 
    origin/v3-0-test
 
    origin/v3-2-stable
 
    origin/v3-2-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.
 
 
 
To present your patchset properly to other developers, please rebase your patches against the branch you are developing against. In particular, if you are developing for Samba 3, please regularly do a
 
  $ git rebase origin/v3-2-test
 
Obviously replace "origin/v3-2-test" by "origin/master", "origin/v3-4-test" or whatever branch you are developing against. If you have created a mess in your local patch queue, "git rebase -i" might help you out.
 
 
 
The final push of the changes to the shared repository is done by team members using the autobuild system.
 
 
 
However, you may push them to your [https://guides.github.com/activities/forking/ own fork on github] or elsewhere with a command like:
 
  $ git remote add github ssh://git@github.com/$USER/samba
 
  $ git fetch github
 
  $ git push github my_branch:my_remote_branch
 
  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
 
 
 
== Some Git Tricks ==
 
 
 
When you have quite some changes to commit, but you want to split them in logically coherent commits you can do that with the following invocation:
 
 
 
  $ git commit -i
 
 
 
When you have commits you want to push, but you want to have the commits to compile on their own, you can insert ''x make -j'' after each commit to check if they do compile one after the other with:
 
 
 
  $ git rebase -i
 
 
 
Last, but not least, when you want to discard part of your changes before committing, you can use:
 
 
 
  $ git reset -p
 
 
 
== Explanation of Branches ==
 
 
 
* The '''master''' branch is the development branch.  Any team member may check into this branch via autobuild after [[CodeReview|code review]].
 
* The '''*-test''' branches are the release series dev branch.  These are under the control of the current release manager for a given release series.
 
* The '''*-stable''' branches are used for release purposes, matching the current release tarball.  These are under the control of the current release manager for a given release series.
 
 
 
The [[Samba Release Planning]] page lists the current branches and their status.
 
 
 
== Creating patches if you don't have write access to git.samba.org repositories ==
 
 
 
If you don't have write access to git.samba.org, using git push to get your changes into Samba is obviously not going to work. In this case, you should create patches. Now, assuming your patches are the last three commits on your current local git branch, this is the easiest way to create patches from them:
 
 
 
  $ git format-patch -3
 
 
 
This will create three patch files in your current directory that you can then send to the samba-technical mailing list.
 
 
 
Note that if you have a number of patches against a specific samba.git branch and don't feel like counting them, the following works as well (e.g. against the master branch):
 
 
 
  $ git format-patch origin/master
 
 
 
This will create one patch file for every patch that is in your local branch but not in origin/master.
 
 
 
If you have more patches which belong together it's sometimes useful to export them into one file:
 
 
 
  $ git format-patch --stdout origin/master > master-featureX-01.patches.txt
 
 
 
== 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/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".
 
 
 
'''Q.''' How can I maintain a feature branch against the upstream Samba branches?
 
 
 
'''A.''' You clone the Samba repository as per the instructions above. Then you make a new feature branch from v3-2-test:
 
$ git branch feature/foo v3-2-test
 
 
 
Now you do your development in your feature branch. Any time the v3-2-test branch gets too different to the code in your feature branch you should rebase your feature branch. The rebase rewinds your feature branch to the point there it was branched. Then it updates you feature branch to the HEAD of the  v3-2-test branch and re-applies your changes.
 
 
 
$ git rebase v3-2-test
 
First, rewinding head to replay your work on top of it...
 
HEAD is now at 357f003... Add WERR_SERVICE_ALREADY_RUNNING.
 
...
 
Wrote tree 02299ef7c1cfa093248bfd9c6e3812805718845e
 
Committed: e20a8c521d7860d9b7bd724ed5ea19c7306530ab
 
 
 
Rebase works best when you use it for local branches that are never pushed to a public repository, see [http://git.or.cz/gitwiki/GitFaq#head-c1dc263aca199d347f28872249e6c1f5d519a2df Why won't "git push" work after I rebased a branch?].
 
 
 
== Suggestions for .gitconfig ==
 
 
 
In order to comply with Samba coding standards and not add new trailing whitespace (see: [http://git.samba.org/?p=samba.git;a=blob_plain;f=README.Coding;hb=HEAD Samba Coding Standards Document]) it is suggested to put:
 
[apply]
 
        whitespace = strip
 
 
 
into your $HOME/.gitconfig file.
 
 
 
That way, whenever you apply a patch using git-am or rebase your work on top of the upstream trees with git-rebase, all newly added whitespace is nicely removed automatically.
 

Latest revision as of 00:39, 23 June 2020