http:///https:///api.php?action=feedcontributions&user=Luk&feedformat=atomSambaWiki - User contributions [en]2024-03-28T16:37:10ZUser contributionsMediaWiki 1.39.5https://wiki.samba.org/index.php?title=Using_Git_for_Samba_Development&diff=6574Using Git for Samba Development2012-05-11T19:57:17Z<p>Luk: Another trick by metze</p>
<hr />
<div>The previous pages based on the git-svn mirror can be found at [[Using Git-SVN for Samba Development (deprecated)]]<br />
<br />
<br />
<br />
== Overview ==<br />
<br />
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 necessary to push after every commit. This should be a familiar work flow for those who have used svk.<br />
<br />
<br />
== Git Installation ==<br />
<br />
* The git source code is available from [http://www.kernel.org/pub/software/scm/git/ http://www.kernel.org/pub/software/scm/git/].<br />
* The project home page is located at [http://git.or.cz/ http://git.or.cz/].<br />
* You should probably familiarize yourself with the [http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html Git tutorial].<br />
<br />
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.<br />
<br />
Note that under Debian or Ubuntu, git is distributed in the git-core package. The git package contains the "GNU Interactive Tools". <br />
<br />
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.<br />
<br />
== Basic Samba Git ==<br />
<br />
<br />
The master git repository is located at ''git://git.samba.org/samba.git''. There is also a [http://gitweb.samba.org/ GitWeb installation].<br />
<br />
'''WARNING:''' ''git://git.samba.org/samba.git'' was previously a git-svn mirror. The mirror has been moved to ''git://git.samba.org/samba-svnmirror.git''.<br />
<br />
Step Zero is to set your name and email address for commits:<br />
<br />
$ git config --global user.email Your.Email@domain.com<br />
$ git config --global user.name "Your Real Name"<br />
<br />
Next, clone the repository:<br />
<br />
$ git clone git://git.samba.org/samba.git samba<br />
Initialized empty Git repository in /home/AD/gcarter/src/git/tmp/samba/.git/<br />
remote: Generating pack...<br />
remote: Done counting 440544 objects.<br />
remote: Deltifying 440544 objects...<br />
remote: 100% (440544/440544) done<br />
Indexing 440544 objects...<br />
remote: Total 440544 (delta 340808), reused 436199 (delta 336480)<br />
100% (440544/440544) done<br />
Resolving 340808 deltas...<br />
100% (340808/340808) done<br />
$ cd samba<br />
<br />
List local and remote branches:<br />
$ git branch<br />
* v3-2-test<br />
<br />
$ git branch -r<br />
origin/HEAD<br />
origin/v3-0-stable<br />
origin/v3-0-test<br />
origin/v3-2-stable<br />
origin/v3-2-test<br />
<br />
Listing tags matching release-3-0-3*<br />
$ git tag -l release-3-0-3*<br />
release-3-0-3<br />
release-3-0-3pre1<br />
release-3-0-3pre2<br />
release-3-0-3rc1<br />
<br />
Creating your own working branch from v3-2-test:<br />
$ git checkout -b my_branch origin/v3-2-test<br />
Branch my_branch set up to track remote branch refs/remotes/origin/v3-2-test.<br />
Switched to a new branch "my_branch"<br />
<br />
Do your own local work:<br />
$ mkdir git-test<br />
$ echo "hello" > git-test/README<br />
<br />
View status of changes<br />
$ git status<br />
# On branch my_branch<br />
# Untracked files:<br />
# (use "git add <file>..." to include in what will be committed)<br />
# <br />
# git-test/<br />
nothing added to commit but untracked files present (use "git add" to track)<br />
<br />
Add our new file to the local branch index:<br />
$ git add git-test<br />
$ git status<br />
# On branch my_branch<br />
# Changes to be committed:<br />
# (use "git reset HEAD <file>..." to unstage)<br />
#<br />
# new file: git-test/README<br />
#<br />
<br />
Commit changes<br />
$ git commit -m "Example file for HOWTO"<br />
Created commit ad9a1eb: Example file for HOWTO<br />
1 files changed, 1 insertions(+), 0 deletions(-)<br />
create mode 100644 git-test/README<br />
<br />
Do some more work and commit local changes....<br />
<br />
Now fetch the remote branch history:<br />
$ git fetch <br />
<br />
Merging remote branch changes:<br />
$ git merge origin/v3-2-test<br />
Already up-to-date.<br />
<br />
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<br />
$ git rebase origin/v3-2-test<br />
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.<br />
<br />
Push the changes to the shared repository<br />
$ git push ssh://git.samba.org/data/git/samba.git my_branch:v3-2-test<br />
updating 'refs/heads/v3-2-test' using 'refs/heads/my_branch'<br />
from f2252e041e075e19bf27e53ab3ed62f39bc8b3e2<br />
to ad9a1eb599c125964ac3e198d3003841edb4c54e<br />
Generating pack...<br />
Done counting 5 objects.<br />
Result has 4 objects.<br />
Deltifying 4 objects...<br />
100% (4/4) done<br />
Writing 4 objects...<br />
100% (4/4) done<br />
Total 4 (delta 1), reused 0 (delta 0)<br />
refs/heads/v3-2-test: f2252e041e075e19bf27e53ab3ed62f39bc8b3e2 -> ad9a1eb599c125964ac3e198d3003841edb4c54e<br />
<br />
== Some Git Tricks ==<br />
<br />
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:<br />
<br />
$ git commit -i<br />
<br />
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:<br />
<br />
$ git rebase -i<br />
<br />
Last, but not least, when you want to discard part of your changes before committing, you can use:<br />
<br />
$ git reset -p<br />
<br />
== Explanation of Branches ==<br />
<br />
The simplest way to explain the existing shared branches is to associate them with the previous SVN ones.<br />
<br />
* 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 and 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 work in progress any longer unless you require some specific testing by the buildfarm.<br />
* The '''master''' branch is the new combined Samba 3 (was: v3-devel) and Samba 4 (was: v4-0-test) development branch. It includes Samba 3 sources in a directory called ''source3'' and Samba 4 sources in a directory called ''source4''. Anyone may check into this branch.<br />
* The '''*-test''' branches correspond to the release series dev branch (e.g. SAMBA_3_2_0). Anyone may check into these branches.<br />
* The '''*-stable''' branches are used for release purposes similar to the SAMBA_X_X_RELEASE branches in SVN. These are under the control of the current release manager for a given release series.<br />
* The '''v3-devel''' branch was the former Samba 3 development branch. It has been turned readonly during the introduction of the '''master''' branch. The '''master''' branch replaces '''v3-devel'''.<br />
* The '''v4-0-test''' branch was the former Samba 4 development branch. It has been turned readonly during the introduction of the '''master''' branch. The '''master''' branch replaces '''v4-0-test'''.<br />
<br />
== Creating patches if you don't have write access to git.samba.org repositories ==<br />
<br />
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:<br />
<br />
$ git format-patch -3<br />
<br />
This will create three patch files in your current directory that you can then send to the samba-technical mailing list.<br />
<br />
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):<br />
<br />
$ git format-patch origin/master<br />
<br />
This will create one patch file for every patch that is in your local branch but not in origin/master.<br />
<br />
If you have more patches which belong together it's sometimes useful to export them into one file:<br />
<br />
$ git format-patch --stdout origin/master > master-featureX-01.patches.txt<br />
<br />
== FAQ ==<br />
<br />
'''Q.''' How do I revert a commit?<br />
<br />
'''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.<br />
<br />
<br />
'''Q.''' Is there a shorthand for git push <URL> <local_repo:remote_repo>?<br />
<br />
'''A.''' Yes. You can define a [remote "upstream"] section in your local repos .git/config file.<br />
<br />
$ git config remote.origin.url ssh://git.samba.org/data/git/samba.git<br />
$ git config remote.origin.push my_branch:v3-2-test<br />
$ cat .git/config<br />
...<br />
[remote "origin"]<br />
url = ssh://git.samba.org/data/git/samba.git<br />
fetch = +refs/heads/*:refs/remotes/origin/*<br />
push = my_branch:v3-2-test<br />
[branch "my_branch"]<br />
remote = origin<br />
merge = refs/heads/v3-2-test<br />
<br />
<br />
'''Q.''' How can I have access to the old CVS and SVN imported repositories via GIT without creating additional cloned repos?<br />
<br />
'''A.''' You can add remote tracking repositories using "git remote":<br />
<br />
$ git remote add cvs git://git.samba.org/import/samba-cvsimport.git<br />
$ git fetch cvs<br />
remote: Generating pack...<br />
remote: Done counting 7070 objects.<br />
Result has 5004 objects.<br />
remote: Deltifying 5004 objects...<br />
remote: 100% (5004/5004) done<br />
Indexing 5004 objects...<br />
remote: Total 5004 (delta 3836), reused 4098 (delta 3044)<br />
100% (5004/5004) done<br />
Resolving 3836 deltas...<br />
100% (3836/3836) done<br />
461 objects were added to complete this thin pack.<br />
* refs/remotes/cvs/APPLIANCE_HEAD: storing branch 'APPLIANCE_HEAD' of git:// git.samba.org/import/samba-cvsimport<br />
commit: af0e201<br />
<br />
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".<br />
<br />
'''Q.''' How can I maintain a feature branch against the upstream Samba branches?<br />
<br />
'''A.''' You clone the Samba repository as per the instructions above. Then you make a new feature branch from v3-2-test:<br />
$ git branch feature/foo v3-2-test<br />
<br />
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.<br />
<br />
$ git rebase v3-2-test<br />
First, rewinding head to replay your work on top of it...<br />
HEAD is now at 357f003... Add WERR_SERVICE_ALREADY_RUNNING.<br />
...<br />
Wrote tree 02299ef7c1cfa093248bfd9c6e3812805718845e<br />
Committed: e20a8c521d7860d9b7bd724ed5ea19c7306530ab<br />
<br />
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?].<br />
<br />
== Suggestions for .gitconfig ==<br />
<br />
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:<br />
[apply]<br />
whitespace = strip<br />
<br />
into your $HOME/.gitconfig file.<br />
<br />
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.</div>Lukhttps://wiki.samba.org/index.php?title=Using_Git_for_Samba_Development&diff=6573Using Git for Samba Development2012-05-11T09:19:05Z<p>Luk: Add 2 useful git tricks, thanks metze</p>
<hr />
<div>The previous pages based on the git-svn mirror can be found at [[Using Git-SVN for Samba Development (deprecated)]]<br />
<br />
<br />
<br />
== Overview ==<br />
<br />
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 necessary to push after every commit. This should be a familiar work flow for those who have used svk.<br />
<br />
<br />
== Git Installation ==<br />
<br />
* The git source code is available from [http://www.kernel.org/pub/software/scm/git/ http://www.kernel.org/pub/software/scm/git/].<br />
* The project home page is located at [http://git.or.cz/ http://git.or.cz/].<br />
* You should probably familiarize yourself with the [http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html Git tutorial].<br />
<br />
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.<br />
<br />
Note that under Debian or Ubuntu, git is distributed in the git-core package. The git package contains the "GNU Interactive Tools". <br />
<br />
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.<br />
<br />
== Basic Samba Git ==<br />
<br />
<br />
The master git repository is located at ''git://git.samba.org/samba.git''. There is also a [http://gitweb.samba.org/ GitWeb installation].<br />
<br />
'''WARNING:''' ''git://git.samba.org/samba.git'' was previously a git-svn mirror. The mirror has been moved to ''git://git.samba.org/samba-svnmirror.git''.<br />
<br />
Step Zero is to set your name and email address for commits:<br />
<br />
$ git config --global user.email Your.Email@domain.com<br />
$ git config --global user.name "Your Real Name"<br />
<br />
Next, clone the repository:<br />
<br />
$ git clone git://git.samba.org/samba.git samba<br />
Initialized empty Git repository in /home/AD/gcarter/src/git/tmp/samba/.git/<br />
remote: Generating pack...<br />
remote: Done counting 440544 objects.<br />
remote: Deltifying 440544 objects...<br />
remote: 100% (440544/440544) done<br />
Indexing 440544 objects...<br />
remote: Total 440544 (delta 340808), reused 436199 (delta 336480)<br />
100% (440544/440544) done<br />
Resolving 340808 deltas...<br />
100% (340808/340808) done<br />
$ cd samba<br />
<br />
List local and remote branches:<br />
$ git branch<br />
* v3-2-test<br />
<br />
$ git branch -r<br />
origin/HEAD<br />
origin/v3-0-stable<br />
origin/v3-0-test<br />
origin/v3-2-stable<br />
origin/v3-2-test<br />
<br />
Listing tags matching release-3-0-3*<br />
$ git tag -l release-3-0-3*<br />
release-3-0-3<br />
release-3-0-3pre1<br />
release-3-0-3pre2<br />
release-3-0-3rc1<br />
<br />
Creating your own working branch from v3-2-test:<br />
$ git checkout -b my_branch origin/v3-2-test<br />
Branch my_branch set up to track remote branch refs/remotes/origin/v3-2-test.<br />
Switched to a new branch "my_branch"<br />
<br />
Do your own local work:<br />
$ mkdir git-test<br />
$ echo "hello" > git-test/README<br />
<br />
View status of changes<br />
$ git status<br />
# On branch my_branch<br />
# Untracked files:<br />
# (use "git add <file>..." to include in what will be committed)<br />
# <br />
# git-test/<br />
nothing added to commit but untracked files present (use "git add" to track)<br />
<br />
Add our new file to the local branch index:<br />
$ git add git-test<br />
$ git status<br />
# On branch my_branch<br />
# Changes to be committed:<br />
# (use "git reset HEAD <file>..." to unstage)<br />
#<br />
# new file: git-test/README<br />
#<br />
<br />
Commit changes<br />
$ git commit -m "Example file for HOWTO"<br />
Created commit ad9a1eb: Example file for HOWTO<br />
1 files changed, 1 insertions(+), 0 deletions(-)<br />
create mode 100644 git-test/README<br />
<br />
Do some more work and commit local changes....<br />
<br />
Now fetch the remote branch history:<br />
$ git fetch <br />
<br />
Merging remote branch changes:<br />
$ git merge origin/v3-2-test<br />
Already up-to-date.<br />
<br />
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<br />
$ git rebase origin/v3-2-test<br />
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.<br />
<br />
Push the changes to the shared repository<br />
$ git push ssh://git.samba.org/data/git/samba.git my_branch:v3-2-test<br />
updating 'refs/heads/v3-2-test' using 'refs/heads/my_branch'<br />
from f2252e041e075e19bf27e53ab3ed62f39bc8b3e2<br />
to ad9a1eb599c125964ac3e198d3003841edb4c54e<br />
Generating pack...<br />
Done counting 5 objects.<br />
Result has 4 objects.<br />
Deltifying 4 objects...<br />
100% (4/4) done<br />
Writing 4 objects...<br />
100% (4/4) done<br />
Total 4 (delta 1), reused 0 (delta 0)<br />
refs/heads/v3-2-test: f2252e041e075e19bf27e53ab3ed62f39bc8b3e2 -> ad9a1eb599c125964ac3e198d3003841edb4c54e<br />
<br />
== Some Git Tricks ==<br />
<br />
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:<br />
<br />
$ git commit -i<br />
<br />
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:<br />
<br />
$ git rebase -i<br />
<br />
== Explanation of Branches ==<br />
<br />
The simplest way to explain the existing shared branches is to associate them with the previous SVN ones.<br />
<br />
* 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 and 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 work in progress any longer unless you require some specific testing by the buildfarm.<br />
* The '''master''' branch is the new combined Samba 3 (was: v3-devel) and Samba 4 (was: v4-0-test) development branch. It includes Samba 3 sources in a directory called ''source3'' and Samba 4 sources in a directory called ''source4''. Anyone may check into this branch.<br />
* The '''*-test''' branches correspond to the release series dev branch (e.g. SAMBA_3_2_0). Anyone may check into these branches.<br />
* The '''*-stable''' branches are used for release purposes similar to the SAMBA_X_X_RELEASE branches in SVN. These are under the control of the current release manager for a given release series.<br />
* The '''v3-devel''' branch was the former Samba 3 development branch. It has been turned readonly during the introduction of the '''master''' branch. The '''master''' branch replaces '''v3-devel'''.<br />
* The '''v4-0-test''' branch was the former Samba 4 development branch. It has been turned readonly during the introduction of the '''master''' branch. The '''master''' branch replaces '''v4-0-test'''.<br />
<br />
== Creating patches if you don't have write access to git.samba.org repositories ==<br />
<br />
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:<br />
<br />
$ git format-patch -3<br />
<br />
This will create three patch files in your current directory that you can then send to the samba-technical mailing list.<br />
<br />
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):<br />
<br />
$ git format-patch origin/master<br />
<br />
This will create one patch file for every patch that is in your local branch but not in origin/master.<br />
<br />
If you have more patches which belong together it's sometimes useful to export them into one file:<br />
<br />
$ git format-patch --stdout origin/master > master-featureX-01.patches.txt<br />
<br />
== FAQ ==<br />
<br />
'''Q.''' How do I revert a commit?<br />
<br />
'''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.<br />
<br />
<br />
'''Q.''' Is there a shorthand for git push <URL> <local_repo:remote_repo>?<br />
<br />
'''A.''' Yes. You can define a [remote "upstream"] section in your local repos .git/config file.<br />
<br />
$ git config remote.origin.url ssh://git.samba.org/data/git/samba.git<br />
$ git config remote.origin.push my_branch:v3-2-test<br />
$ cat .git/config<br />
...<br />
[remote "origin"]<br />
url = ssh://git.samba.org/data/git/samba.git<br />
fetch = +refs/heads/*:refs/remotes/origin/*<br />
push = my_branch:v3-2-test<br />
[branch "my_branch"]<br />
remote = origin<br />
merge = refs/heads/v3-2-test<br />
<br />
<br />
'''Q.''' How can I have access to the old CVS and SVN imported repositories via GIT without creating additional cloned repos?<br />
<br />
'''A.''' You can add remote tracking repositories using "git remote":<br />
<br />
$ git remote add cvs git://git.samba.org/import/samba-cvsimport.git<br />
$ git fetch cvs<br />
remote: Generating pack...<br />
remote: Done counting 7070 objects.<br />
Result has 5004 objects.<br />
remote: Deltifying 5004 objects...<br />
remote: 100% (5004/5004) done<br />
Indexing 5004 objects...<br />
remote: Total 5004 (delta 3836), reused 4098 (delta 3044)<br />
100% (5004/5004) done<br />
Resolving 3836 deltas...<br />
100% (3836/3836) done<br />
461 objects were added to complete this thin pack.<br />
* refs/remotes/cvs/APPLIANCE_HEAD: storing branch 'APPLIANCE_HEAD' of git:// git.samba.org/import/samba-cvsimport<br />
commit: af0e201<br />
<br />
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".<br />
<br />
'''Q.''' How can I maintain a feature branch against the upstream Samba branches?<br />
<br />
'''A.''' You clone the Samba repository as per the instructions above. Then you make a new feature branch from v3-2-test:<br />
$ git branch feature/foo v3-2-test<br />
<br />
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.<br />
<br />
$ git rebase v3-2-test<br />
First, rewinding head to replay your work on top of it...<br />
HEAD is now at 357f003... Add WERR_SERVICE_ALREADY_RUNNING.<br />
...<br />
Wrote tree 02299ef7c1cfa093248bfd9c6e3812805718845e<br />
Committed: e20a8c521d7860d9b7bd724ed5ea19c7306530ab<br />
<br />
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?].<br />
<br />
== Suggestions for .gitconfig ==<br />
<br />
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:<br />
[apply]<br />
whitespace = strip<br />
<br />
into your $HOME/.gitconfig file.<br />
<br />
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.</div>Lukhttps://wiki.samba.org/index.php?title=LinuxCIFS_utils&diff=6565LinuxCIFS utils2012-05-09T12:57:07Z<p>Luk: this wiki will be the new master documentation</p>
<hr />
<div>== Description ==<br />
The in-kernel CIFS filesystem is generally the preferred method for mounting SMB/CIFS shares on Linux.<br />
<br />
The in-kernel CIFS filesystem relies on a set of user-space tools. That package of tools is called '''cifs-utils'''. Although not really part of Samba proper, these tools were originally part of the Samba package. For several reasons, shipping these tools as part of Samba was problematic and it was deemed better to split them off into their own package.<br />
<br />
== News ==<br />
* April 18, 2012: Release 5.4<br />
** the "rootsbindir" can now be specified at configure time<br />
** mount.cifs now supports the -s option by passing "sloppy" to the kernel in the options string<br />
** cifs.upcall now properly respects the domain_realm section in krb5.conf<br />
** unprivileged users can no longer mount onto dirs into which they can't chdir (fixes CVE-2012-1586)<br />
** http://article.gmane.org/gmane.linux.kernel.cifs/5912<br />
* January 28, 2012: Release 5.3<br />
** admins can now tell cifs.upcall to use an alternate krb5.conf file<br />
** on remount, mount.cifs no longer adds a duplicate mtab entry<br />
** the cifscreds utility has seen a major overhaul to allow for multiuser mounts without krb5 auth<br />
** https://lists.samba.org/archive/samba-technical/2012-January/081381.html<br />
* December 09, 2011: Release 5.2<br />
** cifs.idmap can now map uid/gid to SID in addition to the other way around<br />
** getcifsacl/setcifsacl are now installed by default in /usr/bin instead of /usr/sbin. The manpages are now in section 1.<br />
** cifs.upcall has a new scheme for picking the SPN on krb5 mounts. The hostname is now always lowercased. If we fail to get a ticket using an unqualified name, it now attempts to guess the domain name.<br />
** A lot of manpage updates, additions and corrections<br />
* September 23, 2011: Release 5.1<br />
** fix for a minor security issue that can corrupt the mtab<br />
** new getcifsacl/setcifsacl tools that allow you to fetch and set raw Windows ACLs via an xattr.<br />
** a lot of manpage patches<br />
* June 1, 2011: Release 5.0<br />
**mount.cifs always uses the original device string to ensure that umounts by unprivileged users are not problematic<br />
**there is a new cifs.idmap program for handling idmapping upcalls<br />
** a lot of manpage patches<br />
* March 4, 2011: Release 4.9<br />
** Some distros (namely Fedora) are moving to having /etc/mtab be a symlink to /proc/mounts. We automatically skip trying to alter the mtab if it's a symlink. <br />
** fix for a bug that could prevent root from mounting onto a directory to which he did not have explicit execute permission.<br />
** fix for a bug that caused the mount helper to pass in a corrupt address when someone specified an IPv6 address with a scopeid.<br />
** mount.cifs bugfix for an uninitialized variable that could cause a segfault<br />
* January 21, 2011: Release 4.8.1<br />
* January 15, 2011: Release 4.8<br />
* October 19, 2010: Release 4.7<br />
* July 30, 2010: Release 4.6<br />
* May 21, 2010: Release 4.5<br />
* April 28, 2010: Release 4.4<br />
* April 9, 2010: Release 4.3<br />
* April 2, 2010: Release 4.2<br />
* March 23, 2010: Release 4.1<br />
* March 3, 2010: Release 4.0 -- first official cifs-utils release<br />
* February 26, 2010: Release 4.0rc1<br />
* February 14, 2010: The git repo has moved to a new location. See the '''Development''' section below<br />
* February 9, 2010: Release 4.0-alpha1. In order to smooth the transition from shipping these tools as part of samba, the first release will be 4.0.<br />
<br />
== Download ==<br />
A historical set of cifs-utils releases is available in the [ftp://ftp.samba.org/pub/linux-cifs/cifs-utils releases directory].<br />
== Documentation ==<br />
<br />
* [http://pserver.samba.org/samba/ftp/cifs-cvs/linux-cifs-client-guide.pdf Documentation (CIFS Users Guide)]<br />
* <del>[http://www.snia.org/tech_activities/CIFS/CIFS-TR-1p00_FINAL.pdf SNIA CIFS Specification ]</del> broken link<br />
<br />
== Development ==<br />
The source code for cifs-utils is managed via git. An example checkout from the main git repo:<br />
<br />
<pre>$ git clone git://git.samba.org/cifs-utils.git</pre><br />
<br />
gitweb access is also available [http://git.samba.org/?p=cifs-utils.git;a=summary here].<br />
<br />
== Contact ==<br />
Questions, suggestions, concerns, and patches should be sent to [http://vger.kernel.org/vger-lists.html#linux-cifs linux-cifs@vger.kernel.org]. Security issues should be sent to [mailto:security@samba.org security@samba.org] to avoid immediate public disclosure.</div>Lukhttps://wiki.samba.org/index.php?title=LinuxCIFS_utils&diff=6564LinuxCIFS utils2012-05-09T12:54:09Z<p>Luk: TODO: link to reachable specifications (also for smb2/3)</p>
<hr />
<div>== Description ==<br />
The in-kernel CIFS filesystem is generally the preferred method for mounting SMB/CIFS shares on Linux. More information on Linux CIFS is available at the [http://linux-cifs.samba.org/ Linux CIFS VFS] site.<br />
<br />
The in-kernel CIFS filesystem relies on a set of user-space tools. That package of tools is called '''cifs-utils'''. Although not really part of Samba proper, these tools were originally part of the Samba package. For several reasons, shipping these tools as part of Samba was problematic and it was deemed better to split them off into their own package.<br />
<br />
== News ==<br />
* April 18, 2012: Release 5.4<br />
** the "rootsbindir" can now be specified at configure time<br />
** mount.cifs now supports the -s option by passing "sloppy" to the kernel in the options string<br />
** cifs.upcall now properly respects the domain_realm section in krb5.conf<br />
** unprivileged users can no longer mount onto dirs into which they can't chdir (fixes CVE-2012-1586)<br />
** http://article.gmane.org/gmane.linux.kernel.cifs/5912<br />
* January 28, 2012: Release 5.3<br />
** admins can now tell cifs.upcall to use an alternate krb5.conf file<br />
** on remount, mount.cifs no longer adds a duplicate mtab entry<br />
** the cifscreds utility has seen a major overhaul to allow for multiuser mounts without krb5 auth<br />
** https://lists.samba.org/archive/samba-technical/2012-January/081381.html<br />
* December 09, 2011: Release 5.2<br />
** cifs.idmap can now map uid/gid to SID in addition to the other way around<br />
** getcifsacl/setcifsacl are now installed by default in /usr/bin instead of /usr/sbin. The manpages are now in section 1.<br />
** cifs.upcall has a new scheme for picking the SPN on krb5 mounts. The hostname is now always lowercased. If we fail to get a ticket using an unqualified name, it now attempts to guess the domain name.<br />
** A lot of manpage updates, additions and corrections<br />
* September 23, 2011: Release 5.1<br />
** fix for a minor security issue that can corrupt the mtab<br />
** new getcifsacl/setcifsacl tools that allow you to fetch and set raw Windows ACLs via an xattr.<br />
** a lot of manpage patches<br />
* June 1, 2011: Release 5.0<br />
**mount.cifs always uses the original device string to ensure that umounts by unprivileged users are not problematic<br />
**there is a new cifs.idmap program for handling idmapping upcalls<br />
** a lot of manpage patches<br />
* March 4, 2011: Release 4.9<br />
** Some distros (namely Fedora) are moving to having /etc/mtab be a symlink to /proc/mounts. We automatically skip trying to alter the mtab if it's a symlink. <br />
** fix for a bug that could prevent root from mounting onto a directory to which he did not have explicit execute permission.<br />
** fix for a bug that caused the mount helper to pass in a corrupt address when someone specified an IPv6 address with a scopeid.<br />
** mount.cifs bugfix for an uninitialized variable that could cause a segfault<br />
* January 21, 2011: Release 4.8.1<br />
* January 15, 2011: Release 4.8<br />
* October 19, 2010: Release 4.7<br />
* July 30, 2010: Release 4.6<br />
* May 21, 2010: Release 4.5<br />
* April 28, 2010: Release 4.4<br />
* April 9, 2010: Release 4.3<br />
* April 2, 2010: Release 4.2<br />
* March 23, 2010: Release 4.1<br />
* March 3, 2010: Release 4.0 -- first official cifs-utils release<br />
* February 26, 2010: Release 4.0rc1<br />
* February 14, 2010: The git repo has moved to a new location. See the '''Development''' section below<br />
* February 9, 2010: Release 4.0-alpha1. In order to smooth the transition from shipping these tools as part of samba, the first release will be 4.0.<br />
<br />
== Download ==<br />
A historical set of cifs-utils releases is available in the [ftp://ftp.samba.org/pub/linux-cifs/cifs-utils releases directory].<br />
== Documentation ==<br />
<br />
* [http://pserver.samba.org/samba/ftp/cifs-cvs/linux-cifs-client-guide.pdf Documentation (CIFS Users Guide)]<br />
* <del>[http://www.snia.org/tech_activities/CIFS/CIFS-TR-1p00_FINAL.pdf SNIA CIFS Specification ]</del> broken link<br />
<br />
== Development ==<br />
The source code for cifs-utils is managed via git. An example checkout from the main git repo:<br />
<br />
<pre>$ git clone git://git.samba.org/cifs-utils.git</pre><br />
<br />
gitweb access is also available [http://git.samba.org/?p=cifs-utils.git;a=summary here].<br />
<br />
== Contact ==<br />
Questions, suggestions, concerns, and patches should be sent to [http://vger.kernel.org/vger-lists.html#linux-cifs linux-cifs@vger.kernel.org]. Security issues should be sent to [mailto:security@samba.org security@samba.org] to avoid immediate public disclosure.</div>Lukhttps://wiki.samba.org/index.php?title=LinuxCIFS_troubleshooting&diff=5553LinuxCIFS troubleshooting2010-09-20T19:40:49Z<p>Luk: </p>
<hr />
<div>== Asking for Help ==<br />
The best place to ask for help with Linux CIFS is on the [http://vger.kernel.org/vger-lists.html#linux-cifs linux-cifs mailing list]. When asking for help, it's best to provide some basic info:<br />
<br />
* The kernel version you're using (the output of <tt>uname -r</tt>)<br />
* The mount.cifs version you're using (<tt>mount.cifs -V</tt>)<br />
* A clear, concise description of the problem<br />
* A description of the CIFS server with which you're having trouble (Windows version if it's windows, samba version if it's samba, name of the appliance if it's something else)<br />
* if you're able to mount the host, get the contents of '''/proc/fs/cifs/DebugData'''<br />
<br />
== Enabling Debugging ==<br />
The CIFS code contains a number of debugging statements that can be enabled. If you ask for help on the list, one of the developers may ask you for this info. You can also turn it on on your own, but it's not generally helpful unless you're willing to dig into the code.<br />
<br />
To enable debugging, echo a non-zero value into /proc/fs/cifs/cifsFYI. For example:<br />
<br />
<pre><br />
# modprobe cifs<br />
# echo 7 > /proc/fs/cifs/cifsFYI<br />
</pre><br />
<br />
To disable it:<br />
<br />
<pre><br />
# echo 0 > /proc/fs/cifs/cifsFYI<br />
</pre><br />
<br />
These messages end up in the kernel ring buffer. You can view them using '''dmesg'''. <br />
<pre><br />
# dmesg<br />
</pre><br />
<br />
syslog will generally also pick up much of it, but if the rate of messages is rather large, syslog tends to drop some of them. Getting the info straight out of the ring buffer is generally preferred since that's lossless.<br />
<br />
This debugging however can be rather chatty and have a significant impact on performance. It's often best to use this with easily reproducible problems. That is:<br />
<br />
* turn on debugging<br />
* reproduce the issue<br />
* turn off debugging<br />
<br />
Debugging info can contain sensitive data like IP addresses and filenames. Take care when sending this information.<br />
<br />
== Wire Captures ==<br />
<br />
It's sometimes helpful to capture wire traffic between the client and server. The easiest way to do this is with '''wireshark''' which is a graphical network analysis tool. In many cases however, it's not easy or possible to run wireshark directly on one of the hosts. In that case, it's often easier to capture the network traffic in binary format to a file and then feed it into an analyzer to look over it. That also makes it possible to send it to someone who can do some analysis on it.<br />
<br />
Here's an example of doing this:<br />
<br />
<pre><br />
# tcpdump -i eth0 -s0 -w /tmp/cifs-traffic.pcap host cifs_server.example.com and port 445<br />
</pre><br />
<br />
...of course, tcpdump has ''a lot'' of options, so these are just an example. In particular you'll want to modify the capture filter depending on what machine you're running the capture on, etc...<br />
<br />
The captured traffic in this above example will be in /mnt/cifs-traffic.pcap. Before sending these around, it's a good idea to compress them as they squash down fairly well.<br />
<br />
In general, the SMB protocol can be fairly chatty so it's best to use this in a similar manner to the debugging above:<br />
<br />
* start the capture<br />
* reproduce the problem<br />
* stop the capture<br />
<br />
Wire captures can also contain sensitive data like addresses, password hashes, filenames and data. Be careful to whom you send it. In general, don't send this to mailing lists unless you know that the data isn't sensitive.<br />
<br />
== Oopses ==<br />
Occasionally the kernel will panic. When it does, it's helpful to capture the entire message including the kernel messages leading up to the oops. There's a lot of info in an oops message but the main thing that helps debugging is determining where the machine panicked. Here's one way to do this:<br />
<br />
Save off the oops message. The main thing that you see in there is a dump of the registers on the CPU that panicked. For instance, an oops on a 32-bit ix86 machine might look something like this:<br />
<br />
<pre><br />
BUG: unable to handle kernel NULL pointer dereference at 00000414<br />
IP: [<c110d057>] cifs_writepages+0x35/0x60a<br />
</pre><br />
<br />
...the "IP:" line refers to the instruction pointer. That tells us what instruction the CPU was executing at the time that it panicked. The problem is though that due to architecture and compiler differences, etc, we can't directly turn that into a line of code. Here's how to do that:<br />
<br />
Open the kernel module with gdb:<br />
<pre><br />
$ gdb cifs.ko<br />
</pre><br />
<br />
...eventually it should come to a (gdb) prompt. If you're running a vendor kernel, then you may need debuginfo packages for this to work. Once you get a gdb prompt, run:<br />
<pre><br />
(gdb) list *(cifs_writepages+0x35)<br />
</pre><br />
<br />
...obviously, you should replace the stuff in the parenthesis with whatever your oops message says. Pasting the list output can help developers help you.</div>Luk