Git push targets

author	date	tags
PE	2022-09-15	cubi, internal, convention, sop, rule, policy, standard

Git targets for development work

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.

Available on both git servers

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)

Available only on GitHub

1. n/a

Available only on GitLab@HHU

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

SOP: setting up both push targets

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.

Steps

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 git@github.com:core-unit-bioinformatics/git-playground.git
# CUBI convention: gitlab @ HHU gets remote ID "githhu"
$ git remote add githhu git@git.hhu.de:cubi/git-playground.git

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

$ git remote -v
githhu  git@git.hhu.de:cubi/git-playground.git (fetch)
githhu  git@git.hhu.de:cubi/git-playground.git (push)
github  git@github.com:core-unit-bioinformatics/git-playground.git (fetch)
github  git@github.com: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 git@github.com: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 git@github.com:core-unit-bioinformatics/git-playground.git
$ git remote set-url --add --push all git@git.hhu.de:cubi/git-playground.git

6. confirm that all remotes have been set up properly

$ git remote -v
all     git@github.com:core-unit-bioinformatics/git-playground.git (fetch)
all     git@github.com:core-unit-bioinformatics/git-playground.git (push)
all     git@git.hhu.de:cubi/git-playground.git (push)
githhu  git@git.hhu.de:cubi/git-playground.git (fetch)
githhu  git@git.hhu.de:cubi/git-playground.git (push)
github  git@github.com:core-unit-bioinformatics/git-playground.git (fetch)
github  git@github.com: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.

Some further steps

Adding content to a new local branch (no remote counterpart)

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

Switching to a new branch that exists remotely

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

Deleting a branch everywhere

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