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}.
+the directories {\bf rescue} and {\bf docs}. Both repositories are
+hosted on Source Forge.
-We have split the previous SVN repository into two because GIT
-offers enormous advantages for ease of managing and integrating
-developer's changes. One of the disadvantages of GIT is that you
+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
worked on by the developers (bacula, gui, and regress) to a GIT
repository.
-Unfortunately, this requires developers to have a certain knowledege
+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.
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 possibly get your commit privileges
-revoked.
+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 Bacula GIT repository with the
+You can get a full copy of the Source Forge Bacula GIT repository with the
following command:
\begin{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.
+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