Forem: Kacper Rychel

Learn Git fast forward by reproducing GitHub's merges in practice

Kacper Rychel — Tue, 16 May 2023 10:04:52 +0000

We are engineers for many reasons. The common one is we want to know, how it works and how it is made. In this article, I will feed your curiosity hunger for both how it works, showing you how GitHub closes pulls request under the hood, and how it is made, playing with Git commands to reproduce the same result. On top of that, I made a practical brief in fast-forward (--ff, --no-ff, --ff-only) merge strategies in practice. Two birds with one stone 🐦🐦

Note 💬
If you are not interested in details of reproducing the GitHub's pull requests results, you can go straight to the TLDR section, but I do not recommend missing out on the fun 😎

Let's start the adventure.

Table of content

Table of content
--ff, or --no-ff, or ff-only, that is that question
- fast forward in practice
- Bonus puzzle
Closing Pull Request in practice
- Create a merge commit
- Squash and merge
- Rebase and merge
TLDR
Ending

`--ff`, or `--no-ff`, or `ff-only`, that is that question

GitHub merges branches with the --no-ff or --ff-only strategy depending on the closing options.

--ff (fast forward) and --ff-only (fast forward only) simply move a pointer forward. They vary when fast forward is not possible. Then, --ff switches to --no-ff, and --ff-only rejects the operation.

--no-ff (no fast forward) just creates a merge commit.

--ff is a default strategy for git pull and git merge commands.

fast forward in practice

Now, let's see how it works in practice with the initial state:



$ git pull origin feature/4
From https://github.com/zdybasny/git-merges-strategies
 * branch            feature/4  -> FETCH_HEAD
Updating 6cf021a..fa923ee
Fast-forward
 README.md | 4 ++++
 1 file changed, 4 insertions(+)

$ git push

See? Fast-forward was used by default, even if no flag was provided.

The result:

Here is a sample scenario, which fast forward is not possible for:



$ git pull origin feature/5 --ff-only

From https://github.com/zdybasny/git-merges-strategies
 * branch            feature/5  -> FETCH_HEAD
fatal: Not possible to fast-forward, aborting.

The operation was aborted for the --ff-only strategy.



$ git pull origin feature/5 --ff

From https://github.com/zdybasny/git-merges-strategies
 * branch            feature/5  -> FETCH_HEAD
Merge made by the 'ort' strategy.
 new-file.md | 3 +++
 1 file changed, 3 insertions(+)
 create mode 100644 new-file.md

For the --ff strategy, the operation switched to the --no-ff one and created a merge commit:

Bonus puzzle

Being familiar with the fast forward strategy, you can try yourself with a simple puzzle.

What will the command below do for feature/5 branch in current state:

git pull origin main --no-ff?

⁝

Imagine more such merges between more branches 😱

git pull origin main --ff?

⁝

Much cleaner 🤩

Unfortunately, GitHub supports only --no-ff merges, what you will see in the next part of the article.

Closing Pull Request in practice

Create a merge commit

Before starting to play with reproducing the outcome of *Create a merge commit`, let's see what GitHub's documentation says about it:

Merge your commits

When you click the default Merge pull request option on a pull request on GitHub.com, all commits from the feature branch are added to the base branch in a merge commit. The pull request is merged using the --no-ff option.

The feature branch here means the source branch, and the base branch means the target branch.

And this is the result from Github to reproduce:

Knowing the theory and what is to do, we can use following Git commands:

$ git checkout main
$ git pull origin feature/3 --no-ff
$ git push

There are two things to notice:

Even the green branch has been removed, its history still exists. The same will happen if we remove the feature/3 branch. This is exactly the result of the --no-ff strategy of git pull and git merge.
Default messages generated by GitHub and by Git differ.
1. The message generated by Git doesn't include a PR's number. We can still write our own merge commit message and attach a PR reference to it. We must add the -m flag to do so.
2. I described default messages from GitHub in the first post of this series.

As you see, the results are pretty the same, so you know what happens behind the scenes of GitHub when it merges your PR.

Squash and merge

GitHub's documentation says about Squash and merge:

Squash and merge your commits

When you select the Squash and merge option on a pull request on GitHub.com, the pull request's commits are squashed into a single commit. Instead of seeing all of a contributor's individual commits from a topic branch, the commits are combined into one commit and merged into the default branch. Pull requests with squashed commits are merged using the fast-forward option.

The documentation says that the fast-forward strategy is used for squashing. From Git point of view, --squash is the flag of git merge. The statement seems to be informative only, because:

$ git merge origin feature/6 --squash --no-ff
fatal: You cannot combine --squash with --no-ff.

Here is the state to reproduce:

Git CLI commands:

$ git checkout main
$ git merge origin feature/7 --squash

--ff flag could be skipped in the command above because it is the default strategy.

$ git commit

We could also use -m flag to write a message in a terminal inline, but writing it in an editor is more convenient and a there is a default message to edit already.

$ git push

The results look the same but the default commit messages.

Rebase and merge

Rebase is a powerful tool to rewriting a Git history, and its description in the documentation is pretty complex and focused on vary cases. You can just read it on your risk 😉 here: https://git-scm.com/docs/git-rebase. Just kidding, it is worth to read it.

GitHub rebases in only one way, so its documentation is much clearer:

Rebase and merge your commits

When you select the Rebase and merge option on a pull request on GitHub.com, all commits from the topic branch (or head branch) are added onto the base branch individually without a merge commit. In that way, the rebase and merge behavior resembles a fast-forward merge by maintaining a linear project history. However, rebasing achieves this by re-writing the commit history on the base branch with new commits.

The rebase and merge behavior on GitHub deviates slightly from Git rebase. Rebase and merge on GitHub will always update the committer information and create new commit SHAs, whereas Git rebase outside of GitHub does not change the committer information when the rebase happens on top of an ancestor commit

The state to reproduce:

This time, it is not enough to run one or two Git commands to achieve the same result.

Long story short, we need to:

rebase the feature/9 branch onto the main
move the main pointer to feature/9
reset feature/9 to origin/feature/9

So, let's do it step by step.

First, we rebase the feature/9 branch onto the main branch with the flag --force-rebase to achieve a similar state on your local:

$ checkout feature/9
$ git rebase --force-rebase --onto main main feature/9

Here is the difference, which GitHub says in its documentation about. The feature/9 is rebased onto main, but GitHub doesn't touch the source branch. So, you don't as well. You need to just keep the origin/feature/9 as it is. To do so, we need to move the main pointer to feature/9 and reset feature/9 to origin/feature/9. To move the pointer, we will use the fast-forward strategy we have already learned:

$ git checkout main
$ git merge feature/9 --ff-only
$ git push

And now the reset of feature/9:

$ git checkout -
$ git reset HEAD~2 --hard
$ git pull

git checkout - is a shortcut for git checkout @{-1}. It is useful when you need to switch to the previous branch.

The reset command above moved the branch pointer back for 2 commits (HEAD~2) and dropped their changes (--hard).

git pull is for updating the local feature/9 branch to the state of the remote origin/feature/9 branch.

Voilà! 🎉 The result is the same as we did it by using the GitHub's UI.

TLDR

Create a merge commit:

$ git checkout main
$ git pull origin feature/source-branch --no-ff
$ git push

Squash and merge:

$ git checkout main
$ git merge origin feature/source-branch --squash --ff
$ git commit
$ git push --force

Rebase and merge:

$ git checkout feature/source-branch
$ git rebase --force-rebase --onto main main feature/source-branch
$ git checkout main
$ git merge feature/source-branch --ff
$ git push
$ git checkout -
$ git reset HEAD~2 --hard
$ git pull

Ending

I hope you enjoyed our play with Git and GitHub. Asking yourself questions like "How does it work?" and "How can I do it by myself?" is a wonderful way to learn something new. Very often, something we have never thought about before, like me before when I started to draft this article.

This article is the last part of the series, within which I wanted to share with you what options of closing pull requests on GitHub are, when to use them, and now how to do it by yourself. I hope you have found it useful and interesting.

Container runtime vocabulary

Kacper Rychel — Sun, 23 Apr 2023 22:00:00 +0000

Docker became the most popular standard of the containerization. It's so popular that almost everything in the containerized world is called Docker. You can't argue with that. What you can do is learning it. No matter if you are a developer, a sysadmin, or a DevOps engineer, you should know Docker to work with a modern infrastructure.

In this post, I will show you that Docker is only a little part of the containerization now.

So, why almost everything in the containerized world is called Docker❓ What is the difference between a container engine and a container runtime❓ Why is it so confusing❓ What are example tools we can call low-level container runtime and high-level container runtime❓

All these questions and more will be answering in this post.

NOTE
The terminology in the post is linked to each other. You can find:

internal links to other terms within the post

external links to home pages of tools

bold terms (they are described in the previous post of this series: Container and image vocabulary).

Table of contents
Terminology schema
Docker legacy
- Docker breakup
- Container runtime vs container engine
Tool categories
- container runtime - low-level
- container runtime - high-level
- container image build tool
- container orchestrator
- daemon
Standards
- Open Container Initiative
- OCI Image Format Specification (image-spec)
- OCI Distribution Specification (distribution-spec)
- OCI Runtime Specification (runtime-spec)
- OCI Image Configuration
- container image format
- image manifest
- image index
- registry, repository, tag
Ending

Terminology schema

I prepared the next map 🗺️ with relations between terms for you. With it, we can continue our journey.

[The schema was edited on 26-apr-2023]
Podman itself is not a low-level container runtime. It uses crun by default to create and run containers.

Docker legacy

A little historical overview is needed to fairly learn containerization tools and to finally answer the question "why is everything called Docker?".

Docker breakup

When Docker was spreading its popularity, it was a monolith tool. It could build and manage images, transfer them to/from a container registry, run and manage containers, interact with isolated applications and resources withing the containers, and more. Pretty much, isn't it?

Docker Inc. broken up its tool into the modules: runC, containerd, dockerd, and docker CLI client. Some of those modules can be called container runtimes or container engines now. containerd has been donated to Cloud Native Computing Foundation, and runC to Open Container Initiative.

The company, CoreOS, and other leaders in the containerization established Open Container Initiative in 2015. OCI provides standards around the containerization, but Docker Inc. contributes to the runtime specification part only.

Container runtime vs container engine

🔗 🔗

There are no clear definitions of container runtime and container engine. They are used interchangeably. It shouldn't be far from the truth that container runtimes can be divided into to two parts:

low-level container runtime
high-level container runtime.

The container engines can be considered as a high-level container runtimes. They include such features like a user interface (like CLI or REST API) and handling of images. They often call low-level container runtimes to let them create and run containers. In such usage of the terms, low-level container runtimes are called just container runtimes.

Red Hat is the example organization using terms like this, but Docker Inc. mixes both terms within its Docker Engine.

It is not necessary that tools must implement all features destined for container runtimes. Some of tools implement only a part of features and interacts with other container runtime (e.g. dockerd and containerd).

In this post I am going to use the low-level container runtime and high-level container runtime terms. In my opinion they are more accurate.

Tool categories

container runtime - low-level

🔗

Low-level container runtimes are responsible for managing container lifecycle. Nothing more. It means:

creating, starting, stopping, and deleting containers
setting up namespaces, cgroups and operating system security features (like SELinux policies and AppArmor rules) for containers
consuming mounting points (volumes) prepared by high-level container runtimes
and then running commands inside those namespaces and cgroups.

Low-level runtimes abstract the OS primitives only, they are not designed to perform other tasks. They are mostly used by high-level container runtimes. You can interact with them directly, but it is not convenient.

Examples: runC, crun, LXC.

container runtime - high-level

🔗

To fully derive benefits of containerization, it is not enough to just run containers. Their state and networking need to be managed and monitored. Containers are based on images, and images need to be managed. All of that needs to be done in a way that is easy to use and understand for developers, so the layer of interfaces needs to be provided as well.

Common container runtimes can co-work with container orchestrators, han handling individual containers runnings on every node in the cluster.

High-level container runtimes usually:

rely on low-level container runtimes to run containers
set up networking between containers, so that they can communicate with each other, or the outside world
handle inputs over CLI or API
transport container images from/to a registry server
prepare volumes for containers
prepare metadata for low-level container runtimes (e.g., to overwrite CMD)
monitor host resources

Examples of high-level container runtime: containerd, dockerd, CRI-O, LXD, Podman.

container image build tool

🔗

What runtimes can't do, by definition, is building container images (mostly from a Dockerfile). It is a job for container image build tools.

Container runtimes:

may use separate modules (like dockerd using BuildKit, or Podman using Buildah)
may not provide the the feature at all (like CRI-O and containerd).

Examples of image build tools: BuildKit, Buildah, kaniko

container orchestrator

🔗

A container orchestrator does two things:

dynamically schedules container workloads within a cluster of computers
provides a standardized application definition file (kube yaml, docker compose, etc.).

It allows containers within a cluster to be scheduled completely separately. Thanks to that it is easy to:

deploy new instances of the same application into new environments
scale up or down the number of instances of an application
move an application from one environment to another.

On-premise examples: Kubernetes, Docker Swarm.
Examples of cloud vendors' solutions: Amazon ECS, Azure Container Instances.

daemon

Sometimes, you can see a "daemon" term in the context of container runtimes.

The daemon, in general, is a long-running process that performs some tasks in the background. So some container runtimes, their modules, and tools around the containerization can be called like that due to their long-running nature.

The example tools called daemon: dockerd, containerd, LXD, kubelet.

In contrast to those, Podman is the daemonless container runtime.

Standards

Open Container Initiative

🔗

OCI is an open governance structure for the express purpose of creating open industry standards around container formats and runtimes. OCI specification is a set of standards for:

containers image format (image-spec)
runtime (runtime-spec)
distribution (distribution-spec).

OCI develops runC as well.

OCI Image Format Specification (image-spec)

🔗

The image-spec defines an OCI Image, consisting of an image manifest, an image index (optional), a set of filesystem layers, and a configuration. The goal of this specification is to enable the creation of interoperable tools for building, transporting, and preparing a container image to run.

OCI Distribution Specification (distribution-spec)

🔗

OCI distribution-spec defines an API protocol to facilitate and standardize the distribution of content. Container Registry supports pushing and pulling images complaint with OCI image-spec. However, the distribution-spec is designed to be agnostic of content types.

OCI Runtime Specification (runtime-spec)

🔗

OCI runtime-spec aims to specify the configuration, execution environment, and lifecycle of a container created from an OCI Image.

A container's configuration is specified as the config.json for the supported platforms and details the fields that enable the creation of a container. The execution environment is specified to ensure that applications running inside a container have a consistent environment between runtimes along with common actions defined for the container's lifecycle.

OCI Image Configuration

🔗

This specification outlines the JSON format describing OCI images for use with a container runtime and its relationship to filesystem changesets, described in layers.

container image format

🔗

Container runtimes used to have their own container image formats. Docker images formats became the most popular standard. Over time, the industry has established a new standard - OCI Image Format Specification, originally based on the Docker Image Manifest V2, Schema 2.

image manifest

🔗

The manifest is an image format based JSON file that provides configuration and set of layers for a single container image for a specific architecture and operating system.

image index

🔗

The image index is defined by OCI. It is a higher-level manifest which points to specific one or more image manifests, ideal for one or more platforms.

Docker supports manifest list instead of the image index.

registry, repository, tag

The registry is the service to store and download (push/pull) container images. The information about the images is stored in the manifest files.

Images inside the registry are grouped into repositories, and repositories can have subgroups such as organizations, projects, etc. A repository contains multiple tags. Each tag is a pointer to a specific image. The tag is usually a version number, but it can be any string. The default tag is latest. It is mutable (mutable) as opposed to blob sha256 (immutable).

docker run my-registry.com/some-/-organization/repository:tag

Ending

The second part of the containerization journey behind us. You won't be confused anymore when you hear about runtime-related terms, like container runtime, Docker Engine, Podman, containerd, runC.

OCI is a new Docker now.

Now, knowing what is not the Docker, you must be eager to know what actually is it. A part of a Docker tooling has been described here. Next time, I will expand upon the Docker environment. It is still significant part of the containerization world, so it desires for a separate post.

Container and image vocabulary

Kacper Rychel — Mon, 03 Apr 2023 10:00:00 +0000

Kubernetes is a container orchestration system which is used to manage containers grouped in pods which are hosted on nodes. To do that Kubernetes uses an agent called kubelet which uses a Docker (or another container runtime or container engine) which uses a container runtime (once again?) to manage the container lifecycle.

🛑 HOLD ON!

So much layers, terms, and dependencies here. It is not easy to understand how all these components work together. Especially, when some of terms are used interchangeably.

😉 Don't worry.

I will clarify those uncertainties in this series. I will take you on a journey to understand the concept of containers and containerization, and their terms one by one. From bottom to top. From the smallest units, which are system resources and process. At the end of the day, they compute and store your data, not Kubernetes.

In this post I will explain the terms related to containers and images, and a bit of the operating system.

🧭 Let's start the journey!

Table of contents
Terminology on the schema
Operating system specific terms
- process
- resource
- namespace
- cgroups
- SELinux
- AppArmor
- SELinux vs AppArmor
- union mount
- copy-on-write
- overlayFS
Containers and images specific terms
- container
- volume
- image
- base image
- parent image
- layer
- blob
- writable layer
- build
- context
- Dockerfile
- Dockerfile instruction
- entrypoint / cmd
Ending

Terminology on the schema

I prepared a map 🗺️ for you to not get lost in the terminology journey.
The following schema shows the relationship between the terms.

* Docker is only one of container runtimes and can do much more than presented in the map. I will explain it with details in the next post from this series.

Operating system specific terms

process

🔗

A process of an operating system is an instance of a computer program that is being executed by one or many threads. It is a basic unit of work.

resource

🔗

A resource is a hardware of software component managed by an operating system. Resources are allocated to processes to perform some work.

Sample Linux resources:

net - network interfaces
mnt - file system mount points
pid - process ID space
uts - hostname and NIS domain name
user - user and group IDs
ipc - inter-process communication mechanisms.

namespace

🔗

A Linux namespace is functionality of the Linux kernel that isolates and virtualizes system resource. Processes can only interact with resources or processes that are part of the same namespace. Namespaces exist for each type of resource.

Namespaces provide isolation of system resources, and cgroups allow for fine‑grained control and enforcement of limits for those resources.

cgroups

🔗

A control group (cgroup) is a Linux kernel feature that limits, accounts for, and isolates the usage of resources by a collection of processes. Docker relies on cgroups to control and isolate resource limits.

In the context of containers, cgroups limits the resources that each container can consume. cgroups ensures the container has the resources it needs to function properly.

SELinux

🔗 🔗

SELinux (Security-Enhanced Linux) defines access controls for the applications, processes, and files on a system. It uses security policies, which are a set of rules that tell SELinux what can or can’t be accessed. When an application or process makes a request to access an object, like a file, SELinux checks with an access vector cache (AVC), where permissions are cached for subjects and objects. If SELinux is unable to make a decision about access based on the cached permissions, it sends the request to the security server. SELinux supports mandatory access control (MAC).

SELinux is used by containers to control accesses withing them.

AppArmor

🔗 🔗

AppArmor (Application Armor) is security module that you can use to restrict the capabilities of processes running on the host operating system. Each process can have its own security profile. The security profile allows or disallows specific capabilities, such as network access or file read/write/execute permissions. It proactively protects the operating system and applications from external or internal threats. AppArmor supplements the traditional Unix discretionary access control (DAC) model by providing mandatory access control (MAC).

For any given container, you can apply either the default AppArmor security profile, or a custom security profile that you provide.

SELinux vs AppArmor

Most popular Linux distributions contain pre-installed one or both of those security modules.

You could have gotten hold of an impression that SELinux and AppArmor were remarkably similar to each other. It is true. Here you can dive into the comparison between them: https://www.maketecheasier.com/selinux-vs-apparmor/.

union mount

🔗

In computer operating systems, union mount is a technique to mount multiple directories into one that appears to contain their combined contents.

copy-on-write

🔗

It is a technique used to optimize the performance of file systems by copying of a resource only when it is modified. Non-modified resources are shared between the original and the copy of an operation.

overlayFS

🔗

OverlayFS is the union mount implementation included in the Linux kernel since the version 3.18. It implements the copy-on-write technique by overlaying file system layers on top of another one and interacting with the merged result.

OverlayFS is used by Docker to create images and containers.

Containers and images specific terms

container

🔗

A container is a running instance of an image. It is a standardized package containing software along with dependencies, configuration, data, and everything that is needed to run.
From the operating system point of view, a container represents an isolated process (or group of processes) that exists in its own namespace. Processes inside the container do not see processes outside it and vice versa. The container cannot access resources belonging to another container or process resources outside the container.

volume

🔗

A volume is a directory on a host machine that is mounted into one or more containers. It is used to store persistent data outside of the container. It is independent of the container lifecycle. There are three types of Docker volumes:

host volume - lives on the Docker host file system and can be accessed from within the container
named volume - is managed by Docker, where it is created on disk, but is given a name
anonymous volume - is similar to the named volume, but it can be difficult to reference the same volume over time; the volume is managed by Docker, where the files are stored.

image

🔗

An image is a read-only template that is used to create a container. It contains an ordered collection of changes to the root file system and the corresponding execution parameters for use at container runtime. The change of the file system is called a layer. They are stacked on top of each other starting from a base image or from scratch.

An image is built using a Dockerfile.

base image

🔗

A base image does not have a specified parent image in its Dockerfile. It is created using a Dockerfile with the FROM scratch directive.

The base image is usually the latest version of an operating system. It is usually a minimal image, which contains only the operating system and few basic tools.

parent image

🔗

A parent image is an image that is used by another. It is specified in the FROM directive in a child Dockerfile.

layer

🔗

A layer is a modification of an image, represented by a Dockerfile instruction. To create the final image, layers are sequentially applied to the parent image or to the root. When the image is updated or rebuilt, only changed layers need to be updated. Unchanged layers are cached locally to be reused.

blob

🔗

A blob is an immutable binary large object. Blobs are used to store content of the image layers.

writable layer

🔗

When a container is created, a writable layer is created on top of the image. It is a layer that can be modified by the container to store changes made to the container. The writable layer is discarded when the container is deleted.

build

🔗

The process of building a Docker image using a Dockerfile and a context.

Sample tools that implement the build process:

context

🔗

Build’s context is a set of files located in the specified PATH or URL. The build process of an image can refer to any files in the context. For example, your build can use the Dockerfile COPY instruction to reference the file in the context.

Dockerfile

🔗

Dockerfile is a text file that contains instructions for building an image in the order that they are written in the file.

Dockerfile instruction

🔗

A Dockerfile instruction is a command that is executed during the build process. The instructions are executed in the order they are written in the Dockerfile. An instruction can be: FROM, RUN, CMD, LABEL, EXPOSE, ENV, ADD, COPY, ENTRYPOINT, VOLUME, USER, WORKDIR, ARG, ONBUILD, STOPSIGNAL, HEALTHCHECK, SHELL.

entrypoint / cmd

🔗 🔗

If you want your Dockerfile to be able to run without passing additional arguments to the docker run command, you must specify ENTRYPOINT, CMD instructions of both.

CMD is a statement that is run by default when the container is started, but can be easily overridden if the container is started with a command.
ENTRYPOINT is set to a single command. Even if you don't specify ENTRYPOINT, it can be inherited from a parent image. It is not overridden even if the container is started with a command. To override ENTRYPOINT you can use the --entrypoint option of the docker build command.

The instructions are reduced to run the command according to the pattern: <ENTRYPOINT> <CMD>. Therefore, CMD can be used to pass default arguments for the command in ENTRYPOINT.

Ending

Pretty much terms you just learned, aren't they? I gathered them from different sources for you to have a quick reference.

The list is not complete, but it should be enough for you to jump into the world of Docker right now. You've just learned terminology of container components.

Next time I will show you what kind of tools manage them. You will get know what is and what isn't a Docker.
What is the difference between a container engine, a container runtime, and Docker Engine? How does Kubernetes interact with Docker? Does it even use Docker?

I hope you enjoyed this article. If you found it helpful or just liked it, share it with your friends.

Merge, squash & rebase on GitHub - pros & cons

Kacper Rychel — Wed, 15 Mar 2023 23:05:00 +0000

In the previous post, we got to know three ways to close pull requests on GitHub. Their different outcomes for the git history are more accurate for specific scenarios and branching strategies than others. All the closing options have their pros* and cons*. Let’s focus on them in this post and learn how to choose the closing options.

Catches explanation
Even if I list some content under ✅ & ❌ bullet points below, it doesn't mean ✅s are always good and ❌s are always bad. You can consider them more like desired outcomes, and their consequences we need to be aware of.
So yes, the pros and cons phrase here is kind of clickbait 😎

Table of content

Table of content
Pros and cons
- Create a merge commit
- Squash and merge
- Rebase and merge
  - Clean your feature
  - GitHub rebase
A little bit of practice
Summary

Pros and cons

Pardon. Desired outcomes & consequences.

Create a merge commit

Since the Create a merge commit option keeps all commits and branches, it is the easiest way to synchronize branches with each other in both directions. Conflicts between branches, of course, can appear. They are resolved within a new merge commit, so no changes should be lost. It is as easy as it can be, but this easiness can be ugly and messy when we look at the git history.

So, what exactly is wrong with the simple and easy merge?

❌ It generates a new commit which does not provide any meaningful changes. It just merges the history of both branches. Finally, having two branches and the extra commit, the result is not the cleanest we could imagine. Even if a team (or an automated rule) removes all feature branches right after their pull requests are closed, the history of the feature branches remains, and the entire history looks like rails in the train barn.

❌ Bad commit messages are the second awful thing in the "simple merge". We often don't bother about quality of them while we are working on our feature branches (I will call such commits working commits below). It is fine unless such commits are not merged into a long-living branch, like main or develop. Unfortunately, they are merged too often, and they stay there forever.

It is true that bad commit messages are a concern regardless of the way of the pull request closing, but the merge and rebase options preserve all commits in long-living branches.

TIP 💡
I heartily recommend reading the article about How to Write a Git Commit Message.
The approach, described in the article, makes my commits more descriptive and enforces me to think over what I commit. Even when I am still working on my feature branch with my working commits. It taught me discipline.

❌ Even if all contributors wrote really good commit messages, merge commits would still be interspersed with those from deleted (or not yet) feature branches. The commits from the different branches can be even more mixed together in the flatten view of the history on GitHub.

It is tough to recognize which ones belong to which branches or tasks unless we study them in the full git tree.

✅ On the other hand, merge option preserves the entire history if you really need to have such.

✅ The most important benefit of the merge option is that it does not rewrite the history. Rewriting history is especially annoying when you need to compare two branches with the same changes from the same commits, but when the commits have been rewritten.

✅ You can create a next merge commit from the same source branch with new commits to the same target branch (e.g. from develop to main). Changes already merged before are not compared once again.

CONCLUSION 👁️‍🗨️
The Create a merge commit option is the best option for merging code between two long-living branches.

Squash and merge

Using the Squash and merge option, we can simply rephrase our entire work that we did on a feature branch. That way we get rid of multiple working commits with not always meaningful messages. The outcome is one elegant commit.

TIP 💡
Such commit message (according to How to Write a Git...) should contain a short descriptive title (what), an optional body explaining changes (why, not ~~how~~), and a reference to a task ID and/or a pull request.

But what if there was so much to describe and so many changes to compare in one commit? Would it still be elegant?

First things first, when there is too much on commit's plate, it is the forceful signal to distribute changes to multiple commits or/and to split a task into smaller tasks or subtasks.

TIP 💡
A suitable candidate, what we can extract to a separate subtask, is refactor. If your team collects more and more refactoring tasks, I recommend reading the great article about A smooth way to pay your technical debt.

❎ As we rephrase our work during the squash of working commits, we are more likely to catch whether we have made too many changes than during the simple Create a merge commit option.

To give the devil his due, if we fill the pull request descriptions honestly, the chances to catch it will be as high. And even squashes can be made inattentively committing only default messages.

I call taking care of writing good commit descriptions a git hygiene.

TIP 💡
Fill pull requests fields honestly as well.
First, it is a message for your colleagues reviewing your job.
Second, default commit messages on GitHub can be generated from the pull request description and title.

Write descriptive messages of every commit which is supposed to be a part of the pull request.
Exactly for the same reason.

I described default messages generated by GitHub in the previous post Default messages of merge and squash.

End of digressions...
... for now 😉

❌ There is a risk of losing precious information from the git history when a feature branch is removed after it is squashed to a target branch. We need to carefully read messages we want to rephrase.

❌ Have you ever tried to squash the same branch twice?

Let's see the scenario when the 71670e04 commit from the feature/7 has been squashed into the main (f489ebfc), but we pushed another commit into the feature/7 (f4c25692).

We want to squash the new commit to the main.

Yes, there is a conflict, even if a content has been added to the end of the file in the feature/7 and nothing has been changed in the main. Nobody touched the main after our last squash to it. The conflict occurred due to lack of relation between those two branches, so git doesn’t know which change precedes.

Let's take a look what will happen on GitHub when we raise a pull request for the feature/7 :

There are our expected conflict and two commits to merge.

Wait! What? Why are there two commits when the first of them has been squashed into the main already?

What's more, our conflict is even more misleading on GitHub:

This all happens due to the feature/7 and the main have nothing in common after the 93eda5e0 commit. Please remember.

CONCLUSION 👁️‍🗨️
The Squash and merge option is not suitable for using with two long-living branches.
It is the great option to close pull requests of feature branches.

Does it mean Squash and merge is a bad option?

Not at all.

✅✅ Thanks to the squash, we can keep the git history spotless and readable. There are no merge commits which tell us nothing meaningful. Especially when all feature branches are removed after their changes are put into a target branch. We just need to maintain the git hygiene 😷 and not forget about references in the commit messages.

It is much more readable now than when we merged it with the merge commits. We know immediately what and when specific changes have been added to the main.

The abde78a2 commit squashed all commits from the feature/10, both the working commits and the merge commits. If we wanted to keep the commits from the feature/9, it would be better to squash them separately into the main and resolve potential conflicts.

Rebase and merge

Clean your feature

Alternatively, we could drop the merge commits by rebasing the feature/10 locally before we create a pull request and rebase new clean commits into the main by the Rebase and merge closing option of the pull request. Even if we planed to close the pull request with Create a merge commit option, we still could rebase all working commits locally to keep only one well described commit.

✅✅ Rebase is a great tool to clean our feature branch before we raise a pull request. Such rebasing on local is pretty complex and offers many options, but it brings great effects as a final point. It allows us to shape our feature branches to the state we are proud to share within a pull request.

TIP 💡
You can learn more about the most commonly used git commands with the great article: 🌳🚀 CS Visualized: Useful Git Commands. You can also find the explanation with visualizations for Interactive Rebase and Resetting what help you to clean a feature up.

GitHub rebase

Despite the fact the previous section does not deal with the post topic directly, it still is important. Especially when we are going to close our pull request with the Rebase and merge option. All commits from a feature branch are copied into the main. And then it is too late to clean up the commits.

WARNING ⚠️
Never git rebase on public branches, like main or develop.
When somebody had created its feature branch from a commit that has been removed from the origin main, the feature branch is cut off from the origin main as well. The removed commits exist only on the local main. All of them will be considered as new commits during a pull request to the origin main. And that brings vast number of conflicts! Even if such commits contain the same messages and changes, they have the different signatures than the original commits.

Rebasing public branches causes huge trouble to clean the origin up and continue working with the same common code base.

Ok then. Rebase is difficult and dangerous. So, should we avoid using it?

Not really. I strongly encourage learning git rebase, use it locally, and use GitHub's Rebase and merge option when necessary.

✅ Rebase and merge option is pretty similar to the Squash and merge one. It helps us to keep the git history clean and readable without merge commits. The difference is, rebase can add more than one commit into the main.

We just need to maintain the git hygiene and do not forget about references in the commit messages.

❌ This time, in contrast to the squash option, we need to remember adding the references to the messages of feature commits before we can close a pull request. There is no place to edit commit messages within the pull request, like with the squash option where it is possible.

❌ Since commits are copied to a target branch, there is no relation between the source and the target branches. It raises the possibility of having conflicts between changes which are already existing on the both branches. The same case as with the squash option.

CONCLUSION 👁️‍🗨️
The Rebase and merge option is not suitable for using with two long-living branches.
It is the good option to close pull requests of feature branches when you want to keep multiple commits.

A little bit of practice

Probably, the most commonly used branching strategy is Gitflow workflow. It is also one of the most complex strategy. So, let's try to study such case.

As we have learned already, the merge option is suitable to multiple long-live branches like main and develop.

On the other hand, the squash and the rebase options make an excellent job when we want to move changes from a branch which is about to be deleted right after its pull request is closed.

In the picture above, the hotfix is merged into both the main (1) and the develop (2). If the hotfix were squashed or rebased, the same change from the hotfix would be a conflict to itself in the pull request from the release to the main (3).

On the other hand, let see at the develop and feature branches (4). Imagine there are even more feature branches developers are working on in parallel. So, what can we do to avoid the rails in the train barn between the develop and features?

First thing, keep features clean and write good commit messages.

STATEMENT
I know I keep talking about writing good commit messages over and over. I do because they are really that important, and very often neglected by developers. We all are aware of the quality of code and documentation.
And what are commit messages if not the code and the documentation?

The second thing, we can squash features into the main, or rebase them if we would like to keep multiple commits of them.

Summary

We've just learnt more about the outcomes of the options to close pull requests on GitHub, and what consequences they raise. Now, we can handle our pull requests more effectively and wisely. We are not afraid of other options than Create a merge commit anymore.

In the series we learnt what we could use, and when we would have used them.
In the next post we will get to know how GitHub uses git under the hood to give us the discussed outcomes. We will dive a little bit into git commands.

Options to close pull requests on GitHub

Kacper Rychel — Sun, 05 Mar 2023 16:35:28 +0000

One of the common practices of contributing with a developer's solution to a common main code base is Pull Requests.

Are pull requests good practice? Dave Farley doubts it on: Why Pull Requests Are A BAD IDEA.

Table of content

Table of content
Pull Requests on GitHub
Create a merge commit
- Merge in practice
- Default messages of merge
Squash and merge
- Squash in practice
- Default messages of squash
Rebase and merge
- Rebase in practice
- Messages of rebase
Summary

Pull Requests on GitHub

On GitHub, you can choose up to 3 ways of closing them, by adding the code to the main branch. You can choose which ways are allowed for a given repository in its Setting > General:

And this is how it looks like in a pull request:

As we can see, merge, squash, and rebase are explained in the GitHub repository settings and also in pull requests. So, we can close the topic, can't we?

Not just yet. Those commits types are a little bit more complex. You can read more about that in the GitHub documentation. In this post, however, we will go into more details to understand how it looks in practice.

Create a merge commit

he default way of closing a pull request on GitHub is merge. The git documentation says about it:

Incorporates changes from the named commits [...] into the current branch.

What Incorporates mean, it is easier to show than describe, so let's see.

Merge in practice

After Create a merge commit button is pressed, the input fields appear. We can edit a merge commit message here, it is: its title and its body.

This is the result of the Merge pull request:

The changes from the feature have been merged with a new merge commit. Now 007a0485 and 0f830a20 commits are a part of the main, but still only on a side branch.

Now, we can delete the feature from GitHub since deleting feature branches is a good practice. Keep in mind, that branches removed from the origin by GitHub are not removed from your local.

TIP 💡
Do not call your branches just feature or release. Such feature causes troubles with e.g. feature/whatever later.

Default messages of merge

GitHub generates a default commit message depending on a chosen option in repository Setting > General.

Default message

The default message generates a commit title with the pattern: Merge pull request #<PR number> from <source branch>, where #<PR number> is a reference to the current pull request (#2 in the sample above). From Git point of view, it is just a plain text, we can put it to a message even locally. GitHub resolves each #<number> syntax to a link to a pull request of a given repository, even if such a pull request doesn't exist.

The body is consisted of:

merged commit's message - in case of only one commit to merge
PR's title - in case of multiple commits.

Default to pull request title

Only the title of the commit is generated with the pattern <PR title> (#<PR number>). The body is empty.

Default to pull request title and description

In addition to the Default to pull request title, the commit body is copied from the PR's description.

Squash and merge

The second method of closing pull requests on GitHub is squash. According to the Git documentation:

Produce the working tree and index state as if a real merge happened [...]. This allows you to create a single commit on top of the current branch, whose effect is the same as merging another branch.

Squash in practice

This is the result of Squash and merge option on GitHub:

Before:

After:

What happened here?

There is a new commit pushed to the main with the changes from feature/6 branch, but both main and feature/6 branches are not related to each other. It looks like a merge of another branch than feature/6.

After the deletion of feature/6 from both remote and local, the history looks like this:

There is no sign of feature/6 at all. The only trace kept is the reference to a pull request (#3), so pay attention to keeping it in commit messages.

Such result is called linear history. GitHub allows us to enforce such history for given branches as their Branch protection rule. You can read more about it in the documentation: About protected branches > Require linear history.

Default messages of squash

Squash and merge option generates default messages as well, and the same as in Merge pull request option.

Default message

The default message generates a commit depending on a count of commits to squash and merge:

1 commit
- the title pattern: <commit title> (#<PR number>)
- the body is copied from the commit body
multiple commits
- the title pattern: <pull request title> (#<PR number>)
- the body is a list of commits' entire messages

Default to pull request title

The same as in merge's Default to pull request title.

Default to pull request title and commit details

The same as the multiple commits case for default message of squash.

Default to pull request title and description

The same as in merge's Default to pull request title and description.

Rebase and merge

The last GitHub's method of closing a PR is rebase. The Git rebase is a complex and powerful tool that can rewrite a Git history. Fortunately, rebasing by GitHub is limited only to a single specific case. Before I explain it, let’s see what GitHub documentation says:

When you select the Rebase and merge option on a pull request on GitHub.com, all commits from the topic branch (or head branch) are added onto the base branch individually without a merge commit. In that way, the rebase and merge behavior resembles a fast-forward merge by maintaining a linear project history. However, rebasing achieves this by re-writing the commit history on the base branch with new commits.

Rebase in practice

Actually GitHub implements its own way:

The rebase and merge behavior on GitHub deviates slightly from git rebase. Rebase and merge on GitHub will always update the committer information and create new commit SHAs, whereas git rebase outside of GitHub does not change the committer information when the rebase happens on top of an ancestor commit.

And this is how it works in practice:

Right after Rebase and merge button is pressed, there is no input field to provide or edit a commit message this time.

And this is the result after Confirm rebase and merge is pressed:

Similarly to the squash, the merge doesn't bind a source branch to the target one and creates new commits (with new hash) to the target.

Messages of rebase

The difference is that the merge creates commits with the same changes and the same messages as commits in the source branch. After the feature/8 is removed, there is no track where the commit came from.

So, what can we do about that?

We can create a new draft pull request for our feature branch right after it is created. The draft pull request can't be closed nor merged.
Knowing the PR's number, we can just add a reference (#<PR number>) to the titles of our commits of the feature branch.

Summary

Now we know what we can do to close a pull request on GitHub.

Merge joins a source branch with all its commits and a base branch by creating a new merge commit in the base. Such a commit is the point in git history where both branches were bound.
Squash consolidates changes from all commits from a source branch and pushes them together within a new single commit into the base branch. The branches are not bound and the same changes on both branches are considered as totally different ones in comparison.
Rebase copies commits from the target branch and pushes them into the base with the same changes, commit messages, but different SHAs.

In the next post, we will consider when to use the three of them. We will dive into their pros and cons and use cases.

Forem: Kacper Rychel

Learn Git fast forward by reproducing GitHub's merges in practice

Table of content

--ff, or --no-ff, or ff-only, that is that question

fast forward in practice

Bonus puzzle

Closing Pull Request in practice

Create a merge commit

Squash and merge

Rebase and merge

TLDR

Ending

Container runtime vocabulary

Table of contents

Terminology schema

Docker legacy

Docker breakup

Container runtime vs container engine

Tool categories

container runtime - low-level

container runtime - high-level

container image build tool

container orchestrator

daemon

Standards

Open Container Initiative

OCI Image Format Specification (image-spec)

OCI Distribution Specification (distribution-spec)

OCI Runtime Specification (runtime-spec)

OCI Image Configuration

container image format

image manifest

image index

registry, repository, tag

Ending

Container and image vocabulary

Table of contents

Terminology on the schema

Operating system specific terms

process

resource

namespace

cgroups

SELinux

AppArmor

SELinux vs AppArmor

union mount

copy-on-write

overlayFS

Containers and images specific terms

container

volume

image

base image

parent image

layer

blob

writable layer

build

context

Dockerfile

Dockerfile instruction

entrypoint / cmd

Ending

Merge, squash & rebase on GitHub - pros & cons

Table of content

Pros and cons

Create a merge commit

Squash and merge

Rebase and merge

Clean your feature

GitHub rebase

A little bit of practice

Summary

Options to close pull requests on GitHub

Table of content

Pull Requests on GitHub

Create a merge commit

Merge in practice

Default messages of merge

`--ff`, or `--no-ff`, or `ff-only`, that is that question