The CUBI operates with two git hosters:

1. external: github
   • organization: core-unit-bioinformatics
   • git remote ID: github
2. internal: gitlab @ HHU
   • group: cubi
   • git remote ID: githhu

As a simple rule, everything hosted on github must also be available on gitlab @ HHU, but not vice versa.

1. generic workflow repositories
2. templates for workflows
3. bioinformatic tools implemented by the CUBI
4. information sources containing uncritical content such as the knowledge base (wiki)

1. n/a

1. internal (administrative) repositories of the CUBI
2. project repositories containing sample-specific information or project-specific code (used once and only in this context)
3. if in doubt, push to GitLab and add GitHub later

The task is to create a new repository from scratch and to configure it for multiple push targets. There are several ways to get to the same result, depending on where you start. The following series of steps mainly documents git commands and identifiers used for the respective remotes.

Important

If multiple push targets are configured for a repository, github is always the target
platform for development and maintenance (opening issues and pull requests). All changes
are simply pushed to the secondary target (gitlab @ HHU) to ease accessibility from
internal systems.

Deprecation notice

The following series of steps has been automated in the cubi-tools script
auto-git.py. It is strongly recommended to use that tool with the appropriate
preconfigured operation, e.g., clone or init, to perform the below operations
with minimal overhead and predictable outcome.

1. create an empty repository "new-repo" on github and on gitlab
   • in this example, we use "git-playground" as new name
2. on your computer, create a new folder and initialize the git repo

$ mkdir git-playground && cd git-playground
$ git init  # [-b main] for recent versions of git, skip next step
$ git switch -c main  # to create a main branch
Initialized empty Git repository in git-playground/.git/
# if not globally set: configure user name and email
# as appropriate for github
$ git config user.name "USERNAME"
$ git config user.email "EMAIL"

3. next, add both git hosters as push targets:

# CUBI convention: github gets remote ID "github"
$ git remote add github [email protected]:core-unit-bioinformatics/git-playground.git
# CUBI convention: gitlab @ HHU gets remote ID "githhu"
$ git remote add githhu [email protected]:cubi/git-playground.git

4. if you list all configured remotes, it should look like this:

$ git remote -v
githhu  [email protected]:cubi/git-playground.git (fetch)
githhu  [email protected]:cubi/git-playground.git (push)
github  [email protected]:core-unit-bioinformatics/git-playground.git (fetch)
github  [email protected]:core-unit-bioinformatics/git-playground.git (push)

5. pushing to both remotes at the same time can be achieved by creating a third remote that contains both remote URLs

# CUBI convention: the "all" remote covers both push targets.
# Start by setting the primary git for the remote "all" (= github)
$ git remote add all [email protected]:core-unit-bioinformatics/git-playground.git
# and register both remote URLs (github and gitlab) for the push command
$ git remote set-url --add --push all [email protected]:core-unit-bioinformatics/git-playground.git
$ git remote set-url --add --push all [email protected]:cubi/git-playground.git

6. confirm that all remotes have been set up properly

$ git remote -v
all     [email protected]:core-unit-bioinformatics/git-playground.git (fetch)
all     [email protected]:core-unit-bioinformatics/git-playground.git (push)
all     [email protected]:cubi/git-playground.git (push)
githhu  [email protected]:cubi/git-playground.git (fetch)
githhu  [email protected]:cubi/git-playground.git (push)
github  [email protected]:core-unit-bioinformatics/git-playground.git (fetch)
github  [email protected]:core-unit-bioinformatics/git-playground.git (push)
# note here:
# the remote [all] will push to both [github] and [gitlab], but it will
# only fetch from [github] (the primary remote).

7. Fetch new changes from everywhere: git fetch --all [--prune]
   • Here, --all is a modifier of the fetch command, and not the remode identifier all.
   • The --prune modifier removes "dead branches" (deleted in remote) from your local repository.
8. Push changes to all remotes: git push all
   • Here, all is the remote identifier, and not a modifier of the push command.

Situation: you have created a new branch locally via git switch -c BRANCH and want to start working. The Problem: the local branch does not exist in the remotes. Continuing the example above, assume you just started the new repository and have created the main branch.

$ git switch -c main  # main is the branch name
# create your content
$ git add your-content.txt
$ git commit -m "add new content"
$ git push -u all main
# here:
# [-u] is short for "--set-upstream"
# [all] is the remote identifier targeting both github and gitlab
# [main] is again the branch name. This branch will be created in all remotes

Situation: you want to work on a new remote branch that does not yet exist on your local computer.

# make sure you have the latest info from the repository
$ git fetch --all --prune
$ git switch -c BRANCH-NAME --track all/BRANCH-NAME

Situation: the development work for a feature or for fixing an issue has been finished, and the updates were rebased and merged into dev. Do not delete the branch in the web interface of github (which is an action not directly propagated to gitlab), but rather execute the following:

$ git push all :BRANCH-TO-DELETE