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},
+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.
\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
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 git 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}
\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
+where you replace \verb+<xxx>+ with the name
of a directory that you want git to create to hold your local Bacula git
repository.
...
\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.
projects / bacula / docs / blobdiff