\end{itemize}
-\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 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 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
-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 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.
-
-Bacula developers must now have a certain knowledege
-of Git.
-
-\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 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
-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
-\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/}.
-
-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
-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 code, you create a login on
-the Github website:\\
-\elink{http://github.com/}{http://github.com/}\\
-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:bacula/bacula.git <xxx>
-\end{verbatim}
-
-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
-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 ({\bf \verb+<your-name>+/newbranch} 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}
-
-
\section{Developing Bacula}
\index{Developing Bacula}
\index{Bacula!Developing}
projects / bacula / docs / commitdiff