\addcontentsline{toc}{subsubsection}{Patches}
Subject to the copyright assignment described below, your patches should be
-sent in {\bf diff -u} format relative to the current contents of the Source
-Forge GIT repository or SVN repository. The diff -u format is the easiest
-for us to understand and integrate. Please be sure to use the Bacula
+sent in {\bf git format-patch} format relative to the current contents of the
+master branch of the Source Forge Git repository. Please attach the
+output file or files generated by the {\bf git format-patch} to the email
+rather than include them directory to avoid wrapping of the lines
+in the patch. Please be sure to use the Bacula
indenting standard (see below) for source code. If you have checked out
-the source with GIT or SVN, you can get a diff using.
+the source with Git, you can get a diff using.
-For the bacula, gui, and regress directories:
\begin{verbatim}
git pull
-git diff >change.patch
+git format-patch -M
\end{verbatim}
-For the docs or rescue directories:
-\begin{verbatim}
-svn update
-svn diff > change.patch
-\end{verbatim}
-
If you plan on doing significant development work over a period of time,
after having your first patch reviewed and approved, you will be eligible
-for having developer GIT or SVN write access so that you can commit your changes
-directly to the GIT or SVN repository. To do so, you will need a userid on Source
+for having developer Git write access so that you can commit your changes
+directly to the Git repository. To do so, you will need a userid on Source
Forge.
\subsection{Copyrights}
\index{Cycle!Developement}
\addcontentsline{toc}{subsubsection}{Development Cycle}
-As I noted in previous emails the number of contributions are
+As discussed on the email lists, the number of contributions are
increasing significantly. We expect this positive trend
will continue. As a consequence, we have modified how we do
development, and instead of making a list of all the features that we will
\item Kern is the project manager, but prefers not to be a "gate keeper".
This means that the developers are expected to be self-motivated,
- and once they have experience submit directly to the GIT or SVN
+ and once they have experience submit directly to the Git
repositories. However,
it is a good idea to have your patches reviewed prior to submitting,
and it is a bad idea to submit monster patches because no one will
an absolutely trivial bug, create and release a patch file for the
bug. The procedure is as follows:
-Fix the bug in the branch and in the trunk.
+Fix the bug in the released branch and in the develpment master branch.
Make a patch file for the branch and add the branch patch to
the patches directory in both the branch and the trunk.
(input description)
(end edit)
- git diff >>2.2.4-restore.patch
+ git format-patch -M
+ mv 0001-xxx 2.2.4-restore.patch
\end{verbatim}
check to make sure no extra junk got put into the patch file (i.e.
\end{itemize}
-\section{Bacula GIT and SVN repositories}
-\index{GIT and SVN}
-\addcontentsline{toc}{subsection}{GIT and SVN repositories}
-As of August 2009, the Bacula source code has been split into
-two repositories. One is a GIT repository that holds the
+\section{Bacula Git repositories}
+\index{Git}
+\addcontentsline{toc}{subsection}{Git repositories}
+As of September 2009, the Bacula source code has been split into
+three Git repositories. One is a repository that holds the
main Bacula source code with directories {\bf bacula}, {\bf gui},
-and {\bf regress}. The second repository (SVN) contains
-the directories {\bf rescue} and {\bf docs}. Both repositories are
+and {\bf regress}. The second repository contains
+the directories {\bf docs} directory, and the third repository
+contains the {\bf rescue} directory. All three repositories are
hosted on Source Forge.
Previously everything was in a single SVN repository.
-We have split the SVN repository into two because GIT
+We have split the SVN repository into three because Git
offers significant advantages for ease of managing and integrating
-developer's changes. However, one of the disadvantages of GIT is that you
+developer's changes. However, one of the disadvantages of Git is that you
must work with the full repository, while SVN allows you to checkout
-individual directories. If we put everything into a single GIT
+individual directories. If we put everything into a single Git
repository it would be far bigger than most developers would want
-to checkout, so we have left the docs and rescue in the old SVN
-repository, and moved only the parts that are most actively
-worked on by the developers (bacula, gui, and regress) to a GIT
-repository.
+to checkout, so we have separted the docs and rescue into their own
+repositories, and moved only the parts that are most actively
+worked on by the developers (bacula, gui, and regress) to a the
+Git Bacula repository.
-Unfortunately, Bacula developers must now have a certain knowledege
-of both GIT and SVN, and if you are a core Bacula developer knowledge of
-GIT is particularly important.
+Bacula developers must now have a certain knowledege
+of Git.
-\section{GIT Usage}
-\index{GIT Usage}
-\addcontentsline{toc}{subsection}{GIT Usage}
+\section{Git Usage}
+\index{Git Usage}
+\addcontentsline{toc}{subsection}{Git Usage}
-Please note that if you are familiar with SVN, GIT is similar,
+Please note that if you are familiar with SVN, Git is similar,
(and better), but there can be a few surprising differences that
can lead to damaging the history of the repository (repo) if
-you attempt to force pushing data into the GIT repo.
+you attempt to force pushing data into the Git repo.
-The GIT repo contains the subdirectories {\bf bacula}, {\bf gui},
-and {\bf regress}. With GIT it is not possible to pull only a
-single directory, because of the hash code nature of git, you
+The Bacula Git repo contains the subdirectories {\bf bacula}, {\bf gui},
+and {\bf regress}. With Git it is not possible to pull only a
+single directory, because of the hash code nature of Git, you
must take all or nothing.
-For developers, the most important thing to remember about GIT and
+For developers, the most important thing to remember about Git and
the Source Forge repository is not to "force" a {\bf push} to the
repository, and not to use the {\bf rebase} command on the {\bf
master} branch of the repository. Doing so, will possibly rewrite
-the GIT repository history and cause a lot of problems for the
+the Git repository history and cause a lot of problems for the
project.
You may and should use {\bf rebase} on your own branches that you
do not use {\bf rebase} on the {\bf master} branch. The proper
way of merging changes will be discussed below.
-You can get a full copy of the Source Forge Bacula GIT repository with the
+You can get a full copy of the Source Forge Bacula Git repository with the
following command:
\begin{verbatim}
in your current directory, and {\bf trunk} will contain
the subdirectories: {\bf bacula}, {\bf gui}, and {\bf regress}.
-If you have write permission, you can get a copy of the GIT
+If you have write permission, you can get a copy of the Git
repo with:
\begin{verbatim}
\begin{verbatim}
cd trunk
-git pull origin
+git pull
\end{verbatim}
As of August 2009, the size of the repository ({\bf trunk} in the above
from source in this directory and do a lot of updates and regression
testing, the directory could become several hundred megabytes.
-\subsection{Learning GIT}
-\index{Learning GIT}
-If you want to learn more about GIT, we recommend that you visit:\\
+\subsection{Learning Git}
+\index{Learning Git}
+If you want to learn more about Git, we recommend that you visit:\\
\elink{http://book.git-scm.com/}{http://book.git-scm.com/}.
+Some of the differences between Git and SVN are:
+\begin{itemize}
+\item Your main Git directory is a full Git repository to which you can
+ and must commit.
+\item The Git database is kept in the directory {\bf .git} at the
+ top level of the directory.
+\item all the important Git configuration information is kept in the
+ file {\bf .git/config} in ASCII format that is easy to manually edit.
+\item When you do a {\bf commit} the changes are put in {\bf .git}
+ rather than in the external repository.
+\item You can upload your changes to the external repository using
+ the command {\bf git push}.
+\item You can download all the current changes in the external repository
+ and merge them into your {\bf master} branch using the command
+ {\bf gGit pull}.
+\item The command {\bf git add} is used to add a new file to the
+ repository AND to tell Git that you want a file that has changed
+ to be in the next commit. This has lots of advantages, because
+ a {\bf git commit} only commits those files that have been
+ explicitly added.
+\item You can add and commit all files modifed in one command
+ using {\bf git commit -a}.
+\item This extra use of {\bf add} allows you to make a number
+ of changes then add only a few of the files and commit them,
+ then add more files and commit them until you have committed
+ everything. This has the advantage of allowing you to more
+ easily group small changes and commit them.
+\item If you {\bf git pull} from the main repository and make
+ some changes, and before you do a {\bf git push}, someone
+ else pushes changes to the Git repository, you will probably
+ get an error message such as:
+
+\begin{verbatim}
+ git push
+ To git@github.com:bacula/bacula.git
+ ! [rejected] master -> master (non-fast forward)
+ error: failed to push some refs to 'git@github.com:bacula/bacula.git'
+\end{verbatim}
+
+ which is Git's way of telling you that the main repository has changed
+ and that if you push your changes, they will not be integrated properly.
+ As we have noted, you should never ask Git to force the push.
+ See below for an explanation of why.
+\item To integrate (merge) your changes properly, you should always do
+ a {\bf git pull} just prior to doing a {\bf git push}.
+\item If Git is unable to merge your changes or finds a conflict it
+ will tell you and you must do conflict resolution, which is much
+ easier in Git than in SVN.
+\item Resolving conflicts is described below in the {\bf github} section.
+\end{itemize}
+
+If you want to understand why it is not a good idea to force a
+push to the repository, look at the following picture:
+
+\includegraphics[width=0.85\textwidth]{\idir git-edit-commit.eps}
+
+The above graphic has three lines of circles. Each circle represents
+a commit, and time runs from the left to the right. The top line
+shows the repository just before you are going to do a push. Note the
+point at which you pulled is the circle on the left, your changes are
+represented by the circle labeled {\bf Your mods}. It is shown below
+to indicate that the changes are only in your local repository. Finally,
+there are pushes A and B that came after the time at which you pulled.
+
+If you were to force your changes into the repository, Git would place them
+immediately after the point at which you pulled them, so they would
+go before the pushes A and B. However, doing so would rewrite the history
+of the repository and make it very difficult for other users to synchronize
+since they would have to somehow wedge their changes at some point before the
+current HEAD of the repository. This situation is shown by the second line of
+pushes.
+
+What you really want to do is to put your changes after Push B (the current HEAD).
+This is shown in the third line of pushes. The best way to accomplish this is to
+work in a branch, pull the repository so you have your master equal to HEAD (in first
+line), then to rebase your branch on the current master and then commit it. The
+exact commands to accomplish this are shown in the next couple of sections.
\subsection{Publishing your changes}
\index{Publishing}
-Since GIT is more complex than SVN, it takes a bit of time to learn how
+Since Git is more complex than SVN, it takes a bit of time to learn how
to use it properly, and if you are not careful, you can potentially create
-a new history in the repository. In addition, since GIT is a distributed
+a new history in the repository. In addition, since Git is a distributed
version control system, we prefer to receive a full branch submission rather
than simply a patch. To accomplish this, you must create your changes in
a branch, then {\bf push} them to some public repository -- it can be your
own repository that you publish or another. To simplify this phase for you, we
-have created a publich Bacula GIT repository on {\bf github} where you can
+have created a publich Bacula Git repository on {\bf github} where you can
push your branch containing changes you would like integrated into the Bacula
source code.
from your public repository, one of the senior Bacula devlopers will fetch your
changes, examine them, possibly make comments for changes they would like to
see, and as the final step, the senior developer will commit it to the
-Bacula Source Forge GIT repository.
+Bacula Source Forge Git repository.
-\subsection{Github}
+\subsection{github}
\index{github}
-If you are going to submit before cloning the Bacula Github database, you must create a login on
+If you are going to submit code, you create a login on
the Github website:\\
\elink{http://github.com/}{http://github.com/}\\
-You must also upload your public ssh key. Please see the instructions
-at the above link. Then you notify one of the senior Bacula developers,
-who will add your Github user name to the Bacula repository. Finally,
+before you clone the repository.
+You must also upload your public ssh key. Please see the instructions for
+doing so at the above link. Then you notify one of the senior Bacula developers,
+who will authorize your Github user name as a committer to the Bacula repository. Finally,
you clone the Bacula repository with:
\begin{verbatim}
- git clone git@github.com:<username>/bacula.git <xxx>
+ git clone git@github.com:bacula/bacula.git <xxx>
\end{verbatim}
-where you replace \verb+<username>+ with the User Name that you created
-when you created your Github login, and you replace \verb+<xxx>+ with the name
-of a directory that you want git to create to hold your local Bacula git
+where you replace \verb+<xxx>+ with the name
+of a directory that you want Git to create to hold your local Bacula Git
repository.
Normally, you will work by creating a branch of the master branch of your
...
\end{verbatim}
-Note, we request you to create the branch name with your github
+Note, we request you to create the branch name ({\bf \verb+<your-name>+/newbranch} with your Github
login name. This guarantees that the branch name will be unique and
easily identified as well.
If you have completed your edits before anyone has modified the repository,
the {\bf git rebase master} will report that there was nothing to do. Otherwise,
it will merge the changes that were made in the repository before your changes.
-If there are any conflicts, git will tell you. Typically resolving conflicts with
-git is relatively easy. You simply make a diff:
+If there are any conflicts, Git will tell you. Typically resolving conflicts with
+Git is relatively easy. You simply make a diff:
\begin{verbatim}
git diff
\end{verbatim}
-
-\section{SVN Usage}
-\index{SVN Usage}
-\addcontentsline{toc}{subsection}{SVN Usage}
-
-Note: this section is somewhat out of date, since the SVN now
-contains only the docs and rescue subdirectories. The bacula,
-gui, and regress directories are now maintained in a GIT
-repository.
-
-Please note that if you are familiar with CVS, SVN is very
-similar (and better), but there can be a few surprising
-differences.
-
-The Bacula SourceForge.net Subversion repository that contains
-the documentation and the rescue scripts checked out through SVN with the
-following command:
-
-\begin{verbatim}
-svn checkout https://bacula.svn.sourceforge.net/svnroot/bacula bacula
-\end{verbatim}
-
-With the above command, you will get everything, which is a very large
-amount of data:
-
-\begin{verbatim}
-branches/
- Branch-1.32a/
- ...
- Branch-2.0/
- import/
- vendor/
-tags/
- Release-1.1/
- ...
- Release-2.0.2/
-trunk/
- bacula/
- docs/
- gui/
- regress/
- rescue/
-\end{verbatim}
-
-Note, you should NEVER commit code to any checkout that you have
-done of a tag. All tags (e.g. Release-1.1, ... Release-2.0.2)
-should be considered read-only.
-
-You may commit code to the most recent item in
-branches (in the above the most recent one is Branch-2.0). If
-you want to commit code to an older branch, then please contact
-Kern first.
-
-You may create your own tags and/or branches, but they should
-have a name clearly distinctive from Branch-, Release-, or Beta-,
-which are official names used by the project. If you create a
-tag, then you should NEVER commit code to it, for the same
-reason noted above -- it should serve as a marker for something
-you released. If you create a branch, then you are free to
-commit to it as you wish.
-
-You may, of course, commit to the trunk.
-
-In summary:
-
-\begin{verbatim}
-branches
- Branch-nnn
-tags
- Release-nnn
- Beta-nnn
-\end{verbatim}
-
-are reserved names to be created only by the project manager (or
-with his OK), where the nnn is any sequence of numbers and
-periods (e.g. 2.0, 2.0.1, ...).
-
-In addition all tags even those that you create are read-only
-forever. Typically tags represent release points either in the
-trunk or in a branch.
-
-
-Coming back to getting source code.
-If you only want the current Bacula source code, you should see
-the above section that describes the GIT repository.
-
-To view what is in the SVN, point your browser at the following URL:
-http://bacula.svn.sourceforge.net/viewvc/bacula/
-
-Many of the Subversion (svn) commands are almost identical to those that
-you have used for cvs, but some (such as a checkout) can have surprising
-results, so you should take a careful look at the documentation.
-
-The following documentation on the new
-svn repository will help you know how to use it:
-
-Here is the list of branches:
-\begin{verbatim}
- Branch-1.32a
- Branch-1.32e
- Branch-1.34.2
- Branch-1.34.5
- Branch-1.36
- Branch-1.36.1
- Branch-1.36.2
- Branch-1.38
- Branch-2.0
- import
- vendor
-\end{verbatim}
-
-The list of tags is:
-\begin{verbatim}
- Release-1.1 Release-1.19 Release-1.19a Release-1.19b
- Release-1.20 Release-1.21 Release-1.22 Release-1.23
- Release-1.23a Release-1.24 Release-1.25 Release-1.25a
- Release-1.26 Release-1.27 Release-1.27a Release-1.27b
- Release-1.27c Release-1.28 Release-1.29 Release-1.30
- Release-1.31 Release-1.31a Release-1.32 Release-1.32a
- Release-1.32b Release-1.32c Release-1.32d Release-1.32e
- Release-1.32f Release-1.32f-2 Release-1.32f-3 Release-1.32f-4
- Release-1.32f-5 Release-1.34.0 Release-1.34.1 Release-1.34.3
- Release-1.34.4 Release-1.34.5 Release-1.34.6 Release-1.35.1
- Release-1.35.2 Release-1.35.3 Release-1.35.6 Release-1.35.7
- Release-1.35.8 Release-1.36.0 Release-1.36.1 Release-1.36.2
- Release-1.36.3 Release-1.38.0 Release-1.38.1 Release-1.38.10
- Release-1.38.11 Release-1.38.2 Release-1.38.3 Release-1.38.4
- Release-1.38.5 Release-1.38.6 Release-1.38.7 Release-1.38.8
- Release-1.38.9 Release-1.8.1 Release-1.8.2 Release-1.8.3
- Release-1.8.4 Release-1.8.5 Release-1.8.6 Release-2.0.0
- Release-2.0.1 Release-2.0.2
-\end{verbatim}
-
-Here is a list of commands to get you started. The recommended book is
-"Version Control with Subversion", by Ben Collins-Sussmann,
-Brian W. Fitzpatrick, and Michael Pilato, O'Reilly. The book is
-Open Source, so it is also available on line at:
-
-\begin{verbatim}
- http://svnbook.red-bean.com
-\end{verbatim}
-
-Get a list of commands
-
-\begin{verbatim}
- svn help
-\end{verbatim}
-
-Get a help with a command
-
-\begin{verbatim}
- svn help command
-\end{verbatim}
-
-Checkout the HEAD revision of all modules from the project into the
-directory bacula-new
-
-\begin{verbatim}
- svn co https://bacula.svn.sourceforge.net/svnroot/bacula/trunk bacula.new
-\end{verbatim}
-
-Checkout the HEAD revision of the bacula module into the bacula subdirectory
-
-\begin{verbatim}
- svn checkout https://bacula.svn.sourceforge.net/svnroot/bacula/trunk/bacula
-\end{verbatim}
-
-See which files have changed in the working copy
-
-\begin{verbatim}
- svn status
-\end{verbatim}
-
-See which files are out of date
-
-\begin{verbatim}
- svn status -u
-\end{verbatim}
-
-Add a new file file.c
-
-\begin{verbatim}
- svn add file.c
-\end{verbatim}
-
-Create a new directory
-
-\begin{verbatim}
- svn mkdir newdir
-\end{verbatim}
-
-Delete an obsolete file
-
-\begin{verbatim}
- svn delete file.c
-\end{verbatim}
-
-Rename a file
-
-\begin{verbatim}
- svn move file.c newfile.c
-\end{verbatim}
-
-Move a file to a new location
-
-\begin{verbatim}
- svn move file.c ../newdir/file.c
-\end{verbatim}
-
-Copy a file retaining the original history in the new file
-
-\begin{verbatim}
- svn copy file.c newfile.c
-\end{verbatim}
-
-Update the working copy with the outstanding changes
-
-\begin{verbatim}
- svn update
-\end{verbatim}
-
-Compare working copy with the repository
-
-\begin{verbatim}
- svn diff file.c
-\end{verbatim}
-
-Commit the changes in the local working copy
-
-\begin{verbatim}
- svn commit
-\end{verbatim}
-
-Specify which files are ignored in the current directory
-
-\begin{verbatim}
- svn propedit svn:ignore .
-\end{verbatim}
-
-Mark a file to be executable
-
-\begin{verbatim}
- svn propset svn:executable '*' prog.sh
-\end{verbatim}
-
-Unmark a file as executable
-
-\begin{verbatim}
- svn propdel svn:executable prog.sh
-\end{verbatim}
-
-List a file's properties
-
-\begin{verbatim}
- svn proplist file.c
-\end{verbatim}
-
-Create a branch for a new version
-
-\begin{verbatim}
- svn copy https://bacula.svn.sourceforge.net/svnroot/bacula/trunk \
- https://bacula.svn.sourceforge.net/svnroot/bacula/branches/Branch-2.1
-\end{verbatim}
-
-Tag a version for a new release
-
-\begin{verbatim}
- svn copy https://bacula.svn.sourceforge.net/svnroot/bacula/branches/Branch-2.1 \
- https://bacula.svn.sourceforge.net/svnroot/bacula/branches/Release-2.1
-\end{verbatim}
-
-
-Let's say you are working in the directory scripts. You would then do:
-
-\begin{verbatim}
-cd scripts
-(edit some files)
-\end{verbatim}
-
-when you are happy with your changes, you can do the following:
-
-\begin{verbatim}
-cd bacula (to your top level directory)
-svn diff my-changes.patch
-\end{verbatim}
-
-When the command is done, you can look in the file my-changes.patch
-and you will see all the changes you have made to your copy of the
-repository. Make sure that you understand all the changes that
-it reports before proceeding. If you modified files that you do
-do not want to commit to the main repository, you can simply delete
-them from your local directory, and they will be restored from the
-repository with the "svn update" that is shown below. Normally, you
-should not find changes to files that you do not want to commit, and
-if you find yourself in that position a lot, you are probably doing
-something wrong.
-
-Let's assume that now you want to commit your changes to the main
-SVN repository.
-
-First do:
-
-\begin{verbatim}
-cd bacula
-svn update
-\end{verbatim}
-
-When you do this, it will pull any changes made by other developers into
-your local copy of the repository, and it will check for conflicts. If there
-are any, it will tell you, and you will need to resolve them. The problems
-of resolving conflicts are a bit more than this document can cover, but
-you can examine the files it claims have conflicts and look for \lt{}\lt{}\lt{}\lt{}
-or look in the .rej files that it creates. If you have problems, just ask
-on the developer's list.
-
-Note, doing the above "svn update" is not absolutely necessary. There are
-times when you may be working on code and you want to commit it, but you
-explicitly do not want to move up to the latest version of the code in
-the SVN. If that is the case, you can simply skip the "svn update" and
-do the commit shown below. If the commit fails because of a conflict, it
-will tell you, and you must resolve the conflict before it will permit
-you to do the commit.
-
-Once your local copy of the repository has been updated, you can now
-commit your changes:
-
-\begin{verbatim}
-svn commit -m "Some comment about what you changed"
-\end{verbatim}
-
-or if you really only want to commit a single file, you can
-do:
-
-\begin{verbatim}
-svn commit -m "comment" scripts/file-I-edited
-\end{verbatim}
-
-Note, if you have done a build in your directory, or you have added
-other new files, the commit will update only the files that are
-actually in the repository. For example, none of the object files
-are stored in the repository, so when you do a commit, those object
-files will simply be ignored.
-
-If you want to add new files or remove files from the main SVN
-repository, and you are not experienced with SVN, please ask Kern
-to do it. If you follow the simple steps above, it is unlikely that
-you will do any damage to the repository, and if you do, it is always
-possible for us to recover, but it can be painful.
-
-If you are only working in one subdirectory of say the bacula project,
-for example, the scripts directory, you can do your commit from
-that subdirectory, and only the changes in that directory and all its
-subdirectories will be committed. This can be helpful for translators.
-If you are doing a French translation, you will be working in
-docs/manual-fr, and if you are always cd'ed into that directory when
-doing your commits, your commit will effect only that directory. As
-long as you are careful only to change files that you want changed,
-you have little to worry about.
-
-\section{Subversion Resources}
-\index{Subversion (svn) Resources}
-\addcontentsline{toc}{subsection}{Subversion Resources}
-
-Main Subversion Web Page
-\elink{http://subversion.tigris.org}{http://subversion.tigris.org}
-
-Subversion Book
-\elink{http://svnbook.red-bean.com}{http://svnbook.red-bean.com}
-
-Subversion Clients
-\elink{http://subversion.tigris.org/project\_packages.html}{http://subversion.tigris.org/project\_packages.html}
-
- (For Windows users the TortoiseSVN package is awesome)
-
-GUI UNIX client link
-\elink{http://rapidsvn.tigris.org/}{http://rapidsvn.tigris.org/}
-
-A nice KDE GUI client:
-kdesvn
-
-
-
\section{Developing Bacula}
\index{Developing Bacula}
\index{Bacula!Developing}
projects / bacula / docs / commitdiff