+\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
+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
+hosted on Source Forge.
+
+Previously everything was in a single SVN repository.
+We have split the SVN repository into two because GIT
+offers significant advantages for ease of managing and integrating
+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
+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.
+
+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.
+
+\section{GIT Usage}
+\index{GIT Usage}
+\addcontentsline{toc}{subsection}{GIT Usage}
+
+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.
+
+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
+must take all or nothing.
+
+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
+project.
+
+You may and should use {\bf rebase} on your own branches that you
+want to synchronize with the {\bf master} branch, but please
+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
+following command:
+
+\begin{verbatim}
+git clone git://bacula.git.sourceforge.net/gitroot/bacula/bacula trunk
+\end{verbatim}
+
+This will put a read-only copy into the directory {\bf trunk}
+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
+repo with:
+
+\begin{verbatim}
+git clone ssh://<userid>@bacula.git.sourceforge.net/gitroot/bacula/bacula trunk
+\end{verbatim}
+
+where you replace \verb+<userid>+ with your Source Forge login
+userid, and you must have previously uploaded your public ssh key
+to Source Forge.
+
+The above command needs to be done only once. Thereafter, you can:
+
+\begin{verbatim}
+cd trunk
+git pull origin
+\end{verbatim}
+
+As of August 2009, the size of the repository ({\bf trunk} in the above
+example) will be approximately 55 Megabytes. However, if you build
+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:\\
+\elink{http://book.git-scm.com/}{http://book.git-scm.com/}.
+
+
+\subsection{Publishing your changes}
+\index{Publishing}
+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
+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
+push your branch containing changes you would like integrated into the Bacula
+source code.
+
+Once you have pushed your branch to {\bf github} or told us where we can pull
+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.
+
+\subsection{Github}
+\index{github}
+If you are going to submit before cloning the Bacula Github database, you must 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,
+you clone the Bacula repository with:
+
+\begin{verbatim}
+ git clone git@github.com:<username>/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
+repository.
+
+Normally, you will work by creating a branch of the master branch of your
+repository, make your modifications, then make sure it is up to date, and finally
+push it to Github. Assuming you call the Bacula repository {\bf bacula}, you might
+use the following commands:
+
+\begin{verbatim}
+cd bacula
+git checkout master
+git pull
+git branch <your-name>/newbranch
+git checkout <your-name>/newbranch
+(edit, ...)
+git add <file-edited>
+git commit -m "<comment about commit>"
+...
+\end{verbatim}
+
+Note, we request you to create the branch name with your github
+login name. This guarantees that the branch name will be unique and
+easily identified as well.
+
+When you have completed working on your branch, you will do:
+
+\begin{verbatim}
+cd bacula
+git checkout <your-name>/newbranch
+git pull
+git rebase master
+\end{verbatim}
+
+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:
+
+\begin{verbatim}
+git diff
+\end{verbatim}
+
+Then edit each file that was listed in the {\bf git diff} to remove the
+conflict, which will be indicated by lines of:
+
+\begin{verbatim}
+<<<<<<< HEAD
+text
+>>>>>>>>
+other text
+=====
+\end{verbatim}
+
+where {\bf text} is what is in the Bacula repository, and {\bf other text}
+is what you have changed.
+
+Once you have eliminated the conflict, the {\bf git diff} will show nothing,
+and you must do a:
+
+\begin{verbatim}
+git add <file-with-conflicts-fixed>
+\end{verbatim}
+
+Once you have fixed all the files with conflicts in the above manner, you enter:
+
+\begin{verbatim}
+git rebase --continue
+\end{verbatim}
+
+and your rebase will be complete.
+
+If for some reason, before doing the --continue, you want to abort the rebase and return to what you had, you enter:
+
+\begin{verbatim}
+git rebase --abort
+\end{verbatim}
+
+Finally to upload your branch, you do:
+
+\begin{verbatim}
+git push origin <your-name>/newbranch
+\end{verbatim}
+
+If you wish to delete it later, you can use:
+
+\begin{verbatim}
+git push origin :<your-name>/newbranch
+\end{verbatim}
+
+
projects / bacula / docs / commitdiff