Chapter 21

Merging Small Projects

In the initial phase of a project, prototypes for critical design decisions and technologies are often implemented. When the evaluation is complete, you would want to combine the successful prototypes to form the first version of the overall project.

In such a scenario, the prototypes are often versioned in separate repositories. Once the entire project is started, a common repository is preferred, i.e., the files of the various prototypes need to be merged.

In another scenario, initially projects were too modularized and versioned in different repositories. It later turns out that often simultaneous changes are made and files often need to be moved between repositories. In this case too, is a single repository useful.

The workflow in this chapter shows how multiple repositories can be merged with Git so that

• the histories of all files and
• the tags of all repositories are kept.

Overview

This workflow is based on Git’s ability to import commits from different remote repositories to a repository using the fetch command. Git does not require that the commits to be imported have a common origin.

The top section of Figure 21.1 shows two repositories named backend and ui that will be used as examples.

After importing the commits to a repository, there are two separate commit histories. If you switch between commits in the backend project and the ui project, then only the files of the selected project will be displayed in the workspace.

The important step towards a common project version is to merge the independent commit histories using the merge command.

In preparation for the merge, it makes sense to create a new root directory for each of the projects and move all the existing files to this directory (the new directories are backend and ui). After the merge, the root directory of the common project will contain two subdirectories (backend and ui) (see the bottom section of Figure 21.1).

This approach will prevent conflicts during a merge.

Requirement

Different tag names: Each project must use a unique tag name, i.e., you cannot have identical tags in different repositories. If there are identical tags, you must delete these tags or add new tags with a unique name.

Workflow “Merging Small Projects”

Several projects, each with a separate repository, are merged into a common repository. The commit histories of the projects must remain.

Figure 21.1: Workflow overview

Process and Implementation

Combine Repositories

In the following sequence we use two repositories (ui and backend) as an example. Each repository has a master branch. As a result, we want to merge both into a single repository that only has one master branch.

Step 1: Create a main repository

First, the new common repository is created as a clone of the backend repository and switched to the new workspace.

> git clone backend common

> cd common

Step 2: Move the files in the project directory (first repository)

So that merging with another project does not cause file conflicts, create a new folder.

> mkdir backend 

Then, move all files to the new directory. To do this, use the mv command. This moves files and directories at the operating system level and at the same time performs the necessary add and rm commands to take the changes into the next commit:

> git mv src test backend 

Finally, complete the changes with the commit command.

> git commit -m "backend directory created"

Step 3: Import the second repository

To import the ui repository, we create a new remote in the common repository.

> cd common

> git remote add ui ../ui/ 

Using the fetch command, import all the Git objects (branches, tags, commits) from the ui repository into the common repository.

> git fetch ui 

Attention! If there is a tag name in the ui repository that already exists in the common repository, it will be ignored.

Step 4: Move the files to the project directory

Next, create a new project directory named ui from the imported UI project. Since the name of the branch in the UI project is also master, and this name is already used by the branch from the backend project, you have to choose another name (uimaster) for the local branch.

> git checkout -b uimaster ui/master 

The parameters used are as follows.

-b: A new branch must be created and activated.

uimaster: The name of the local branch.

ui/master: The reference to the master branch in the remote of the ui repository.

The creation of the project directory and the moving of the files are the same as Step 2

> mkdir ui 

> git mv src test ui 

> git commit -m "ui directory created"

Step 5: Merge the projects

After both projects were imported into the common repository and each is in its own project directory, a merge is performed.

The merge will take place on the master branch, so this branch needs to be activated.

> git checkout master 

With the merge command, the uimaster branch is merged with the master branch. Since both projects have different project directories, there may not be merge conflicts.

> git merge uimaster

The result of the merge operation can be shown with the “graphical” log command. It is good to see that the commits of the two original projects are developed independently from each.

> git log --graph --oneline 

* e40fcb2 Merge branch 'uimaster' 
| 
| \ 
| * ace51c9 ui directory created
| * 40feb24 foo and bar added
* f8bd134 backend directory created
* fa1482a bar added 
* bddfa53 foo added 

The uimaster branch can now be deleted, since it was only needed temporarily for the merge.

> git branch -d uimaster 

That’s it. Now there is a common repository that includes the histories and tags of both project repositories.

Why Not the Alternatives?

Why Not Do without New Project Directories?

Can we skip Steps 2 and 4? Why do we have to move the project files to their own directories?

If you do not create the new directories, the merge command will try to merge the root directories of both projects and their files. Existing files will be combined and conflicts will have to resolved.

If you are merging two previously independent projects, it makes sense in the rarest of cases to combine files with the same name. In most cases you will want to rename or move a file. This is easier to perform directly at the file level than in the middle of a merge operation.

The procedure described shows it is possible to merge files by creating new module directories and then versioning them.