DEV Community: José David Ureña Torres

How SSH Works—and How It Breaks: A Practical Guide to Secure Remote Access

José David Ureña Torres — Sun, 29 Mar 2026 01:04:45 +0000

Introduction

SSH (Secure Shell) is a cornerstone of modern computing. It’s no exaggeration to say that almost every software engineer and IT administrator has used an SSH client to manage a remote machine at some point of their careers. This protocol has been around since 1995 and it remains the gold standard of secure shell access.

SSH provides encrypted tunnels over insecure networks, allowing secure access to remote machines. While the protocol itself is very robust and mature, its security ultimately depends on how it is used. Misconfigurations, inexperience and lack of knowledge can be an open door for attackers.

And I’m speaking from experience. I've used SSH in insecure ways in the past, mainly because I didn’t fully understand how to protect my systems and applications correctly.

In this series of three parts, we will explore how SSH can be misused, how attackers exploit common pitfalls, and how to avoid them.

In the first part, we’ll discuss why you shouldn’t blindly trust the server you’re connecting to, and provide a high-level overview of how host key verification works.

In the second part, we'll go through a small lab exercise to demonstrate a Man-in-the-Middle (MITM) attack, showing how an attacker can capture credentials and monitor live user activity.

The last part focuses on hardening and best practices. We’ll cover practical, actionable security measures to protect your infrastructure and applications.

Let’s get started.

Why hostnames and IP addresses cannot be trusted for SSH authentication

When you SSH to a remote machine, are you sure you are connecting to the right server? You might think that double-checking the hostname or IP address eliminates the risk, but that's not true. Verifying a destination address is not enough to guarantee a server's identity.

At first glance, trusting an SSH connection based on a hostname seems secure. If you point your client toward server.example.com, it feels like you must be connecting to the right place, right? However, hostnames and IP addresses are not inherently trustworthy, especially outside private networks; they depend on multiple layers of infrastructure that can be manipulated.

For this reason, SSH security relies on cryptographic host key verification rather than simply trusting where the network appears to be routing your traffic.

Common Attack Vectors

There are different methods that can be used to redirect a connection to a malicious server without you even noticing, including:

DNS poisoning
Host file poisoning
Network-level and routing attacks

We will cover these attacks in the following sections.

DNS poisoning

When you connect using a hostname (e.g., ssh server.example.com), your system relies on DNS to resolve it to an IP address. Because low-level network communication requires IP addresses rather than human-readable names, this resolution step is a critical point of failure.

In a DNS poisoning attack, an actor corrupts this resolution process so that a legitimate hostname resolves to a malicious IP address. This silently redirects your SSH connection, making the redirection nearly impossible to detect if you rely solely on the hostname for trust.

Hosts file poisoning

Operating systems can override external DNS resolution using a local hosts file (e.g., /etc/hosts on Linux). If an attacker gains sufficient access to your machine, they can modify this file to force trusted hostnames to point to malicious IP addresses.

While an attacker with this level of access could likely cause even more damage to your machine, this technique remains effective because it is simple and redirects traffic without raising immediate suspicion. It is important to note that hosts file poisoning is not a network attack, but rather a post-compromise persistence or redirection technique that bypasses DNS entirely.

Network-level and routing attacks

Even if your DNS and local configurations are secure, the network path itself may be compromised. Attackers who control or compromise routers and switches can intercept or alter traffic in transit. This enables man-in-the-middle attacks, particularly on untrusted networks like public Wi-Fi or poorly secured internal LANs.

At a larger scale, global internet routing can be manipulated as well. Attacks such as Border Gateway Protocol (BGP) hijacking allow malicious actors to redirect traffic through attacker-controlled networks, even when the destination IP address seems correct. Furthermore, IP addresses themselves are not permanent guarantors of a server's identity.

In cloud environments, for example, IPs are frequently reassigned, meaning an address you trusted yesterday may belong to a completely different system today.

Host Key Verification: How SSH Verifies the Server's Identity

When you connect to a remote machine for the first time using SSH, your client likely does not know the server's public key yet. That is because the client has no record of this server, it will present a cryptographic fingerprint and ask if you want to proceed:

The authenticity of host 'ssh-lab-server (172.18.3.102)' can't be established.
ED25519 key fingerprint is SHA256:lgJpFZwUmV3iwY7kp9+gsiFrczV2/o3dIzP9kBq5czE.
This key is not known by any other names.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

When you type yes, the server's public key is saved to the ~/.ssh/known_hosts file in your home directory. You can inspect this file to see the stored key:

$ cat ~/.ssh/known_hosts
ssh-lab-server ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEOQy4+6J3BirR3SuwLPRweCiTvkC/oVSdw/4XPBvm4t

When the Fingerprints Don't Match

The next time you connect, the SSH client will compare the key provided by the server against the one stored in your known_hosts file. If they match, the connection proceeds.

However, if the host key does not match, the OpenSSH client blocks the connection and displays an alarming warning:

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
Someone could be eavesdropping on you right now (man-in-the-middle attack)!
It is also possible that a host key has just been changed.
The fingerprint for the RSA key sent by the remote host is
SHA256:8o/qY3/YXiEUh5yHMH5Xe6Zpekiroj5QTVSBt7cF03o.
Please contact your system administrator.
Add correct host key in /home/myclient/.ssh/known_hosts to get rid of this message.
Offending ED25519 key in /home/myclient/.ssh/known_hosts:1
Host key for ssh-lab-server has changed and you have requested strict checking.
Host key verification failed.

This is the default behavior of the OpenSSH client, and it is your primary line of defense. It forces you to stop and investigate what happened, before continue and potentially send data or credentials to a malicious server.

But What Is a Fingerprint in the First Place?

An SSH key fingerprint is a condensed, hash-based and fixed-length representation of a much larger public key.

You might wonder: Why do we need a fingerprint if we can just check the public key directly? Essentially, for human readability and consistency. Public keys can be incredibly long and vary in size depending on the algorithm used (RSA vs ED25519). Displaying a short, fixed-length fingerprint is much more convenient for manual verification, logging, and monitoring.

For example, consider this known_hosts file generated by pulling the public keys for GitHub:

$ ssh-keyscan github.com >> ~/.ssh/known_hosts
$ cat ~/.ssh/known_hosts
github.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCj7ndNxQowgcQnjshcLrqPEiiphnt+VTTvDP6mHBL9j1aNUkY4Ue1gvwnGLVlOhGeYrnZaMgRK6+PKCUXaDbC7qtbW8gIkhL7aGCsOr/C56SJMy/BCZfxd1nWzAOxSDPgVsmerOBYfNqltV9/hWCqBywINIR+5dIg6JTJ72pcEpEjcYgXkE2YEFXV1JHnsKgbLWNlhScqb2UmyRkQyytRLtL+38TGxkxCflmO+5Z8CSSNY7GidjMIZ7Q4zMjA2n1nGrlTDkzwDCsw+wqFPGQA179cnfGWOWRVruj16z6XyvxvjJwbz0wQZ75XK5tKSb7FNyeIEs4TT4jk+S4dhPeAUC5y+bDYirYgM4GC7uEnztnZyaVWQ7B381AK4Qdrwt51ZqExKbQpTUNn+EjqoTwvqNj4kqx5QUCI0ThS/YkOxJCXmPUWZbhjpCg56i+2aB6CmK2JGhn57K5mj0MNdBXA4/WnwH6XoPWJzK5Nyu2zB3nAZp+S5hpQs+p1vN1/wsjk=
github.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBEmKSENjQEezOmxkZMy7opKgwFB9nkt5YRrYMjNuG5N87uRgg6CLrbo5wAdT/y6v0mKV0U2w0WZ2YB/++Tpockg=
github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl

As you can see, the keys have different lengths, especially the RSA key, which is quite huge. Trying to visually compare those strings would be a nightmare. However, if we compute the fingerprints using ssh-keygen, the data becomes much more manageable:

$ ssh-keygen -l -f ~/.ssh/known_hosts
3072 SHA256:uNiVztksCsDhcc0u9e8BujQXVUpKZIDTMczCvj3tD2s www.github.com (RSA)
256 SHA256:p2QAMXNIC1TJYWeIOttrVc98/R1BUFWu3/LiyKgUfQM www.github.com (ECDSA)
256 SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU www.github.com (ED25519)

Much easier to read, isn't it?

Common Questions and Misconceptions

If I see a host key verification error, am I under a man-in-the-middle attack?

Not necessarily, but you should never ignore the error. A server's public key can change for legitimate reasons, such as:

The server was rebuilt or reinstalled, generating new keys.
The OS was upgraded or reconfigured.
You are connecting to a new instance behind a load balancer or an autoscaling group.
The infrastructure is ephemeral (e.g., cloud instances frequently destroyed and recreated).
The administrator intentionally rotated the keys for security.

You must verify that this change is valid before proceeding.

Why would anyone intentionally disable host key verification?

It often happens because skipping the check feels "simpler" during development, especially when learning to use SSH libraries. These libraries often include warning logs specifically to alert developers who forget to implement verification. While disabling it might save time during a "Hello World" project, it creates a massive security hole if that code ever reaches production.

What if I’m connecting via VPN or a private network?

You might argue that internal infrastructure is "safe," but that is exactly the assumption attackers rely on. However, once an attacker is inside your VPN, they can compromise one or more machines. The risk is lower than the open internet, but it is never zero.

What about automation tools like Ansible?

This is one of the most common places where verification is disabled. Developers are often tempted to bypass host key verification to avoid friction when configuring and managing environments.

This is typically done in one of three ways:

In the configuration file: By setting host_key_checking = False inside the [defaults] section of the ansible.cfg file.
As an environment variable: By exporting ANSIBLE_HOST_KEY_CHECKING=False in the terminal session before running a playbook.
Directly at SSH level: By specifying StrictHostKeyChecking=no as a connection argument, via ansible_ssh_common_args.

While this simplifies the first stages of a project, it is a habit that must be broken. Eventually, you should implement a proper verification strategy (like using a Certificate Authority or pre-populating known_hosts), especially when connecting to machines outside your immediate control.

Do testing environments really need this level of caution?

You might think a test server has no useful data, but that depends on your configuration. Attackers often use "low-value" environments as a stepping stone. If your test environment uses the same credentials or has network access to your production database, a stolen SSH session on a testing machine could potentially compromise the rest of the company's infrastructure.

The risk is naturally lower when working with ephemeral and immutable infrastructure, where machines are frequently destroyed and recreated. In contrast, environments with long-lived infrastructure should always apply strict SSH host key verification practices.

Conclusion

In this first part, we discussed how SSH verifies a server's identity and why hostnames and IP addresses are not reliable guarantors of that identity. We explored how attackers can manipulate network infrastructure via DNS poisoning, host file modification, or routing attacks to take advantage of poor SSH configurations. Knowing the risks of improper SSH configurations is the first step toward hardening applications and infrastructure that rely on SSH.

In the next article, we will move from theory to practice. We’ll walk through a lab exercise to demonstrate exactly how an attacker can steal credentials and monitor live user activity using a man-in-the-middle attack.

Stay tuned for Part 2!

Bibliography

Clouflare | 2026 | What is DNS cache poisoning?
eG Innovations | 2026 | What is Ansible?
Ergaster | 2023 | Should you check SSH fingerprints?
Mercans | 2026 | Why SSH Fingerprint Verification Is Essential for Secure SFTP Access: Meeting Industry Standards

Linux Without Fanboyism: An Honest Developer’s Perspective

José David Ureña Torres — Sun, 14 Dec 2025 00:02:44 +0000

Introduction

As a software engineer, I try not to get too attached to a single operating system. Computers are just tools we use to get the job done, and unless your work depends on platform-specific software, most modern operating systems will serve you well.

Whenever possible, I like to use more than one operating system to avoid being biased by personal preferences. In this article, I’ll share my personal experience using Linux as a daily desktop operating system, highlighting both the good and the bad.

Everything here reflects my own opinions and experiences, so keep in mind that they may be subjective.

This article is aimed at developers and technical users who are curious about Linux as a desktop operating system, especially those coming from Windows or macOS. If you’re looking for an honest, experience-based perspective rather than a sales pitch, this is for you.

My Linux Journey

If you thought I was going to talk about how Linux is the best operating system and why all the others are garbage, you’re wrong. And this is probably not the article for you. I’ve used Windows, Linux, and macOS, and I like them all. Each one shines in different situations.

I’m not the person who will tell you that Windows is evil or that you’re a superior human being if you compile the Linux kernel yourself. Windows is great, and if you don’t have a good reason to try Linux, that’s totally fine.

That said, I do have a nostalgic relationship with Linux.

When I started college, I couldn’t afford a new computer. I was using an old laptop that struggled with basic tasks like web browsing, office work, and coding. I planned to replace it by the end of the year, but in the meantime I needed a way to make it usable. I didn’t want to go into debt just to buy a computer.

While researching ways to reduce resource usage, I discovered Linux. What caught my attention were stories about how it could give old computers a second life.

As a beginner, I ran into many problems installing and configuring it, mostly because I wasn’t familiar with the terminal. After a few days of trial and error, I managed to install everything I needed for college, and the machine became usable again, at least long enough for me to save up for a new one.

Of course, I broke my system a few times along the way and dealt with the usual beginner issues: Wi-Fi problems, hardware compatibility quirks, laggy video playback, and poor battery life. I eventually fixed most of them, except for battery life, which is still a common challenge on some laptops today.

Despite the frustration, that period taught me a lot about how computers and operating systems actually work. I spent hours reading documentation and forum posts to solve these problems.

Today, I use a MacBook Air for portability, but I also have a desktop PC that I built specifically to run Linux. I don’t have enough time to experiment with new distributions as much as I used to, but I still enjoy using Linux regularly and staying connected to the ecosystem.

The good parts

The appeal of Linux

Once you’re comfortable with Linux, you start missing some features when using other operating systems. Personally, I love how easy it is to install and uninstall software using a package manager like apt or dnf. Windows has Chocolatey and macOS has Homebrew, but Linux package managers generally feel more integrated and robust.

Highly customizable

Linux gives you a high level of control over your computer. You can customize the operating system to fit your needs. Of course, this varies depending on the distribution and the desktop environment you’re using, but most distros offer extensive customization options.

You can install several desktop environments at once: GNOME, KDE, XFCE, i3, dwm, etc. Linux’s modular nature makes it easy for them to coexist.

Familiar if you use Linux at work

If you already use Linux at work, such as when connecting to remote machines or managing a VPS on a cloud provider, using Linux on your personal machine feels natural. It’s also a great way to practice and improve your skills.

The knowledge you gain often becomes useful later when dealing with servers, Docker containers, or production environments.

Docker containers run natively on Linux

Containers are a lightweight form of operating-system-level virtualization. They package applications and all their dependencies into an isolated, portable, and consistent environment.

This technology is fundamentally a Linux feature. Docker is mostly an orchestrator and convenience layer; the actual containerization is handled by the Linux kernel itself. To simplify a bit, containers are regular Linux processes that run directly on the host kernel, but inside restricted environments created using namespaces (to isolate things like filesystems, networking, and PIDs) and cgroups (to limit CPU, memory, and other resources).

Because this relies on Linux kernel features, Docker Desktop on Windows and macOS uses an additional virtualization layer to provide a Linux environment.

Scripting and automation

Linux is also great for writing scripts or automate repetitive tasks. You can write Bash, Python, or Go scripts and run them as systemd services, or add them to your PATH so they behave like regular commands.

Of course, most of this is possible on other operating systems, but I personally find it easier and more natural to do on Linux.

The trade-offs

Things can break

Especially if you’re new and don’t fully know what you’re doing, things are more likely to break or not work as expected. On Windows, things usually “just work”, and that’s probably what I like the most about it: you plug something in, and it magically works. At least that has been my experience with Windows. On Linux, be prepared to spend time reading documentation and troubleshooting issues.

And sometimes it’s not even your fault. Even though Linux itself is generally rock-solid, that doesn’t mean all software running on Linux is bug-free. In many cases, companies don’t invest much effort into fixing Linux-specific issues because their main target audience uses Windows or macOS. It is what it is. You learn to deal with it and move on.

Learning curve

Linux can be intimidating at first. You need to learn new ways of doing things that you were already comfortable with on Windows or macOS. In many cases, you’ll have to learn the “Linux way”.

New users also have to decide which Linux distribution they want to install, and the differences between them are not always clear. And Linux has many different distributions. Also, depending on the distro, you also need to choose a desktop environment from several options. All of this can be confusing at the beginning.

You’ll also find yourself using the terminal more often. On Linux, typing a command sometimes feels faster and easier than clicking through a graphical interface. I know, it sounds contradictory. Why would typing commands be faster than clicking icons and menus? But trust me, most Linux users would probably agree: typing commands somehow just feels faster.

Hardware support

This is another point in favor of Windows. On Linux, some hardware may need extra configuration or may not work perfectly. I’ve experienced issues with multi-monitor setups, headphones, and HDMI connections, not necessarily due to faulty hardware, but because of drivers, firmware, or display-server quirks. Multi-monitor setups often depend on graphics drivers and desktop environment settings, while headphones and HDMI sometimes require minor tweaks. Tasks like these can occasionally be tricky, though support has improved significantly in recent years.

If you’re building a new PC specifically to run Linux, my recommendation is to first verify that your hardware is well supported. Some components can still be problematic depending on the setup. For example, NVIDIA GPUs may require extra configuration or proprietary drivers, which can occasionally lead to issues.

Despite careful hardware selection, some minor problems can still occur.

Software compatibility

Not all software is available on Linux. Microsoft Office and Adobe applications are two common examples. While open-source alternatives exist, you may feel that they don’t fully match their proprietary counterparts.

For document and spreadsheet editing, for example, I usually rely on the web version of Office 365, which is more than enough for my needs. I also keep LibreOffice installed, just in case.

Open-source software is created and maintained by communities and companies, but these projects aren’t always driven by profit. In many cases, contributors and maintainers aren’t making any money from it, so don't blame them. I say “in many cases” because there are open-source projects that do have a business model behind, such as VS Code or Next.js.

Most contributors work on these projects simply because they want to. Remember, they also have personal lives and often full-time jobs. Depending on the project, you can contribute as well. So if you’re a developer and have some free time when you encounter a bug, consider investigating it, you might find a fix and submit a Pull Request. Even small contributions like this help improve open-source software for everyone.

That way, we can all contribute to open-source software, even in small ways. But I know, that’s much easier said than done.

Despite these downsides, most of the problems I’ve mentioned can be avoided or mitigated with some guidance. Hardware compatibility, as well as choosing a distribution and desktop environment that suit your needs, play a major role in how smooth or frustrating your Linux experience will be. The next sections focus on practical tips to help you get started on the right foot.

Choosing the right hardware for you

There’s no magic advice here; do your homework. First, determine your hardware needs and research components based on that. You can use websites like Linux Hardware to look up specific components; it was very helpful for me.

If you’re buying a PC piece by piece, try to avoid hardware that is known to be problematic on Linux, such as certain NVIDIA GPUs or very recent components that haven’t been properly tested yet.

Reddit forums are also a great resource for researching hardware compatibility issues on Linux.

Choosing the right Linux distribution for you

A Linux distribution is a complete operating system that includes the Linux kernel, usually the GNU user-space tools and libraries, a package manager, some preinstalled applications, and default configurations. A desktop environment may also be included, depending on the distribution.

There are many articles and videos about Linux distributions. Others may disagree, but if you’re just starting out, I think there are only three you need to consider: Ubuntu, Linux Mint, and Fedora.

For your first Linux distribution, I’d recommend choosing either Mint or Ubuntu. You can’t really go wrong with either. I prefer Linux Mint because it feels more familiar if you’re coming from Windows, but both are excellent choices. Linux Mint is based on Ubuntu.

For developers, Fedora can also be a solid option. It’s a more bleeding-edge distribution, which means it includes newer packages compared to Ubuntu and Mint. It also tends to ship new features earlier, which may take some time to appear in other distributions. However, this also means you might encounter occasional errors or compatibility issues that are less common in more stable distributions.

There are other distributions that I think are better suited for more advanced users, or at least users who already have strong preferences. Debian and Arch Linux fall into this category. They are great distributions, but probably not ideal as a first distro.

Personally, I use Fedora on my desktop PC today, but years ago I used Linux Mint as my main system. Both have been very good experiences.

Choosing the right desktop environment for you

This largely depends on the distribution you choose. For example, Ubuntu comes with a customized version of GNOME. Linux Mint offers three editions: Cinnamon (the default), MATE, and XFCE.

Fedora provides even more options on its website, including GNOME (default), KDE Plasma, XFCE, LXQt, and Cinnamon.

If you’re not sure which desktop environment to choose, install a few of them and try them out. On Linux, you can have multiple desktop environments installed at the same time.

If you don’t want to experiment too much, you can safely choose between GNOME or KDE. KDE is usually a solid choice if you’re coming from Windows.

Nowadays, the desktop environment I use is XFCE because it’s very lightweight and works well out of the box. There’s no particular reason beyond that. I installed it, it worked well, and I stuck with it. No reason to change.

A few common questions

Is Linux for everyone?

No. If your work depends heavily on proprietary software or specific hardware that doesn’t work well on Linux, it may not be the right choice; and that’s okay.

Should you switch to Linux full-time?

Not necessarily. Many people, including me, benefit from using Linux alongside Windows or macOS, either on a separate machine, a dual-boot setup, or a virtual machine.

Is it worth trying Linux at least once?

Definitely. Even if you don’t stick with it, the experience can teach you a lot about operating systems, tools, and how computers work.

If you are already using Linux, should you switch to another distribution?
It depends, but usually no. If you’re switching just because of FOMO, it’s probably not worth it. If you’re facing a specific issue and you’ve confirmed that it’s handled better on another distribution, then switching can make sense. That said, hardware issues are rarely fixed simply by changing distros.

Conclusion

This article reflects my personal experience with Linux, and yours may be very different. My main recommendation is to try a few distributions using VirtualBox or similar virtualization tools and see what works best for you. Once you choose one, try to stick with it for a while instead of constantly distro-hopping. If I had to recommend a single distribution to start with, I can confidently suggest Linux Mint.

Once you step into the Linux world, try not to become overly “religious” about it. Avoid distro wars and pointless debates, especially on forums and social media. Just relax, learn, explore, and enjoy the experience.

For me, learning Linux has been a very positive experience. Early in my career as a software engineer, even a basic understanding of Linux helped me work more efficiently and understand systems at a deeper level. Even if Linux never becomes your main operating system, the knowledge you gain from using it will almost certainly pay off.

I can’t promise you’ll love Linux, but you might. Either way, it’s worth trying at least once.

Bibliography

Arch Linux Wiki | 2025 | Arch compared to other distributions
Arch Linux Wiki | 2025 | Desktop environment
Hardware for Linux | 2025 | Hardware for Linux
Red Hat | 2017 | Containers are Linux
Red Hat | 2025 | What is a Linux container
Wikipedia | 2018 | List of Linux Distributions

Building A Minimal SSH Server in Go

José David Ureña Torres — Tue, 02 Sep 2025 05:21:57 +0000

SSH is one of those technologies we often take for granted. Most engineers use it daily to connect to and manage remote machines. It’s a foundational part of internet infrastructure, and the modern digital world would look very different without it.

It enables secure remote access over unsecured networks, relying on cryptography to authenticate and encrypt connections between devices.
As a weekend project, I’ve been building a minimal SSH server in Go. My goal wasn’t to reinvent the wheel, but to gain a deeper understanding of the protocol’s inner workings.

My experience with SSH was primarily as a user: opening terminals, setting up port forwarding, and occasionally tweaking the sshd_config file to suit specific needs. Like many engineers, I've always found it a bit magical. You type a command, and boom: you are connected to a remote machine. I wanted to understand what happen behind the scenes.

When I want to learn something new, my usual approach is to study the theory first, reading articles and documentation or doing an online course depending on the case, and then try to wrap up that knowledge by building a small project. Getting your hands dirty is, in my opinion, one of the best ways to truly internalize a concept.

In this reading, I'll walk you through how I built a minimal SSH server as a weekend project. If you're just here for the code, feel free to jump to the GitHub link at the end. The README file has all the information you need of how to compile and use the application.

I'll also share my thought process as a software engineer when tackling a new project. Keep in mind this was a time-boxed experiment, so I made a few trade-offs to keep things simple and focused. Still, if you're a college student or someone learning to code, I hope this gives you some insight into how small projects can complement your learning journey.

Why An SSH Server?

One option was to build an SSH client instead, which would've been an interesting choice too. But creating something that could run as a service, managed by tools like systemd on Linux, sounded more appealing.

After thinking about it, I decided to explore the server side of the SSH protocol and write a small SSH server. I wanted to go deep enough to understand the core message flow that makes SSH connections work.

So I spent a few days reading about the SSH protocol in my free time. After that, I scoped out the requirements for my weekend project.

Overview of SSH Channel Types and Requests

This section provides a high-level overview of key aspects of the SSH protocol, focusing on the events and messages I needed for this project.

The SSH protocol runs over TCP and supports multiple channel types, each serving different purposes. Some channels handle data streams, while others are designed to process request messages.

SSH Channel Types

Each channel type defines what the channel is used for:

session: The most common channel type. Used for remote shells, and command execution and subsystems.
x11: Used for X11 forwarding. Allows remote GUI apps to display locally via the X Window System.
forwarded-tcpip: Used for local port forwarding. Data sent to a local port is forwarded through the SSH tunnel to a destination host/port.
direct-tcpip: Used for remote port forwarding. The remote SSH server connects to a specified address/port and sends data through the tunnel back to the client.

In addition to these, OpenSSH defines some extended channel types that are not part of the official SSH protocol:

direct-streamlocal@openssh.com: Used for forwarding Unix domain sockets. It's similar to direct-tcpip, but forwards socket paths instead of TCP ports.
forwarded-streamlocal@openssh.com: Used for forwarding Unix domain sockets in the opposite direction.

Channel Requests

The session channel is the main channel type that receives channel requests. Other channels, such as x11, direct-tcpip, and forwarded-tcpip, do not receive channel requests. Those are primarily used for raw data forwarding.

Here is a list of the most common requests types:

pty-req: Requests a pseudo-terminal for interactive shell.
shell: Starts an interactive shell session.
exec: Executes a single command.
subsystem: Requests a subsystem (e.g., sftp).
x11-req: Requests X11 forwarding for the session.
env: Sets environment variables.
window-change: Notifies of window size changes.
signal: Sends POSIX signals (e.g., SIGINT) to the remote process.
exit-status: Sent by server to indicate process exit code.
exit-signal: Sent by server to indicate process was terminated by signal.

Project Scope and Technical Approach

This section describes the project scope and the requirements I chose to include. In real-world projects, features typically go through several rounds of refinement before development begins. The final output often consists of a set of well-defined tickets, each with specific tasks and clear acceptance criteria.

Features

The goal was to build a very minimal SSH server with support for two use cases: executing a single remote command and starting an interactive shell session.

If you are not familiarized with this terms, when using the OpenSSH client, you can run a remote command like this:

ssh <user>@<address> <command>
ssh myuser@x.x.x.x echo hello world

Or for starting an interactive shell you can omit the command as follows:

ssh <user>@<address>
ssh myuser@x.x.x.x

I decided to add support for only these two use cases. While adding features like port forwarding might be fun in the future, for this initial version I wanted to focus on the most basic functionality.

The server must close the sessions properly once the remote command finishes, or when the user exits the shell or terminates the process.

Authentication

SSH typically supports two main authentication methods: password authentication and public key authentication.

At first glance, password authentication might seem easier to implement. However, it actually requires handling interactive password prompts, which adds complexity. To keep things simple, I decided to go with public key authentication for this initial version.

With this approach, I just need to generate an SSH key pair and provide an authorized_keys file. This file tells the server which public keys are allowed to authenticate.

To connect, the user must specify their private key explicitly:

ssh -i <path-to-private-key> <user>@<address>

Note: It might seem that we are sending the private key to the server, but actually not. The SSH client derives the public key from the private key, which is what actually gets sent to the server for authentication.

SSH server configuration

I initially considered creating a simplified version of /etc/ssh/sshd_config, the configuration file used by the OpenSSH server. But for this minimal project, I only needed a few basic settings to customize the application.

So, I went with a simple YAML file that gets read at startup. This allows the application to specify things like the network interface and port to listen on, or which users are allowed to connect, and that is more than enough for the scope of this project.

Access control

I decided to implement an allowlist-based access control model using an authorized_users setting in the config file. With this approach, only the users listed there are allowed to connect.

In a typical SSH setup, the server reads each user's ~/.ssh/authorized_keys file, and you can add a public key for a particular user with the ssh-copy-id command. But for simplicity, this implementation reads a single authorized_keys file specified in the config. That also means multiple users can authenticate using the same key, as long as they possess it.

Additionally, the application should read the /etc/passwd file to ensure that the user exists, have a home directory and a default login shell.

Concurrency

The application needs to allow multiple clients connected at the same time. For this minimal version, we can skip using a thread pool or any advanced scheduling, but the design must still support concurrent usage from the beginning.

Testing

At a minimum, there should be tests covering the most essential scenarios:

Can a user connect with a valid key?
Does the server reject unknown users or invalid keys?
Can the server execute a single command correctly?
Can the server start an interactive shell session?
Can the server handle multiple simultaneous user connections?

Language

As the title already suggests, this project was written in Go. It's a solid choice for scripting, command-line tools, small APIs, socket programming, and services that run as background processes on the Operating System.

It offers excellent built-in support for networking and concurrency, making it a natural fit for implementing an SSH server. And since it’s a compiled language, packaging and running the final application is simple and efficient.

Coding phase

Since this project focuses only on executing single commands and starting interactive shells, the only channel type I needed to implement was the session one. I didn't have to support every possible request type, but at least the essentials: exec, shell, and pty-req.

High-Level Steps

Here is what the application needs to do:

Read the configuration file, which defines allowed users, the listening address, and the port.
Read information about the authorized users, like uid, gid, home directory and default login shell.
Initialize the SSH server using these settings.
Load the server’s private key, which acts as the host key. (In OpenSSH, these are typically located in /etc/ssh/.)
Start a TCP listener on the configured interface and port.
Ignore non-session channels, since only session is supported in this version.
Handle exec, shell, and pty-req requests on session channels.
For exec requests, run the provided command and return the output.
For interactive sessions, pty-req usually arrives before the shell request, so save the terminal info to be used when launching the shell.

Challenges

Most of the implementation went smoothly, but there were a few tricky areas:

Managing stdout and stderr from the command or shell process correctly without blocking the stream of data. I ended up using separate Go routines to stream output back to the client.
Minor issues parsing SSH keys due to a mistake in the authorized_keys file. I used a wrong format for the public keys.
Implementing PTY handling, especially attaching the shell to a pseudo-terminal to support features like prompts and signal handling. This feature was not implemented completely, proper signal handling and terminal modes is pending.
Had some issues closing the session correctly. It was not working correctly at first, causing the connection to freeze on the client side. It was being caused by a channel not being closed properly.
Commands must be executed as the connecting user. To achieve this I required to add cap_setuid and cap_setgid capabilities to the binary, which was not part of my plan. Without those capabilities the application does not have enough permissions to run commands as other users.
While writing integration tests, I found that OpenSSH is slightly more permissive than the Go SSH library when handling certain protocol errors from the server. In some cases, the code worked with the OpenSSH client but failed with the Go SSH library. But this was actually good, as it helped me to improve the implementation to better align with the SSH standard.

Eventually, I got everything working. I took inspiration from a couple of excellent resources to solve some of the harder parts:

Gopher Academy (2015) - Building an SSH Server in Go
Gliderlabs (2025) - Gliderlabs SSH Package

Source code

If you want dive into the code it's available on my Github. Feel free to explore, clone it, or use it as a reference for your own experiments.

Bibliography

Cloudfare - 2025 - What is SSH
Digital Ocean - 2025 - SSH essentials: Working with ssh servers clients and keys
The Internet Society - 2006 - RFC 4250
The Internet Society - 2006 - RFC 4251
The Internet Society - 2006 - RFC 4252
The Internet Society - 2006 - RFC 4253
The Internet Society - 2006 - RFC 4254

Understanding ICMP: How to Send and Receive ICMP Messages in Go

José David Ureña Torres — Mon, 24 Feb 2025 04:28:03 +0000

Introduction

If you like video games you have probably heard the term ping. In gaming, ping measures the round-trip time (RTT) it takes for a packet to travel from your device to the game server and back. This is a key component of network latency. When playing an online game, higher latency means that it takes longer for messages between your computer and and the other players' computers, resulting in bad gameplay performance Schnutzel, 2021. Additionally, we can use ping to check whether we can reach a machine or if it is accessible from our own computer.

Have you wondered how it works? Ping relies on ICMP, a protocol used for network diagnostics and error reporting. Actually, you can try it out by opening a terminal and typing the following command:

bash-3.2$ ping www.google.com

PING www.google.com (142.250.64.132): 56 data bytes
64 bytes from 142.250.64.132: icmp_seq=0 ttl=114 time=54.802 ms
64 bytes from 142.250.64.132: icmp_seq=1 ttl=114 time=51.040 ms
64 bytes from 142.250.64.132: icmp_seq=2 ttl=114 time=48.910 ms

Note the time value in each message, indicating the latency between my computer and the destination machine. The output also includes useful information like the number of bytes sent and how many hops the packet can take before being discarded (TTL).

However, if we try to reach a host that does not exist or it is not available we get the following response:

ping 127.0.0.2                                                                                                        2 х │ 10:01:29 PM
PING 127.0.0.2 (127.0.0.2): 56 data bytes
Request timeout for icmp_seq 0
Request timeout for icmp_seq 1
Request timeout for icmp_seq 2

This article demonstrates how to send and receive ICMP messages using Go. For simplicity, I decided to cover only Echo and Echo Reply. If you want to learn more about other ICMP types and codes I encourage you to read the RFC 792 standard, the official specification for ICMP.

Why Go?

Other languages like C, C++ or even Rust might be preferred under certain circumstances. However, Go is still a solid choice for this type of applications. It offers an easy-to-read syntax, with the advantages of statically typed languages. Moreover, Go is efficient in terms of speed and executable size because it is a compiled language.

The Go icmp package provides structs for ICMP messages, allowing us to avoid crafting the packets manually. We will be using that package through this guide.

Understanding ICMP

The Internet Control Message Protocol (ICMP) is a fundamental component of the Internet Protocol Suite, primarily used for diagnostic and error-reporting purposes. Unlike TCP or UDP, ICMP is not used for transmitting application data but rather for sending control messages that help manage network behavior.

ICMP messages are commonly associated with network utilities like ping and traceroute, which rely on it to test connectivity and trace the route of packets across a network. These messages can indicate unreachable destinations, packet loss, or excessive delays, making ICMP essential for network troubleshooting and performance monitoring.

Despite its usefulness, ICMP can also be exploited for network attacks, such as ICMP flood (ping flood) or smurf attacks, leading to its restriction or filtering in certain environments. However, when used correctly, ICMP remains a vital tool for understanding and maintaining network health.

ICMP packet structure


   0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     Type      |     Code      |          Checksum             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |           Identifier          |        Sequence Number        |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     Data ...
   +-+-+-+-+-

This is the structure of an ICMP Echo packet, commonly used for ping requests and replies. Here's a breakdown of each field:

Type (8 bits): Specifies the message type. Echo Request = 8, Echo Reply = 0.
Code (8 bits): Provides additional information. For Echo messages, this is always 0.
Checksum (16 bits): Used for error-checking the packet.
Identifier (16 bits): Helps match requests with replies.
Sequence Number (16 bits): Tracks the order of packets.
Data (Variable length): Contains the payload, e.g: timestamps.

List of ICMP Messages

Type	Message Name	Code	Description
0	Echo Reply	0	Response to an ICMP Echo Request (ping response).
3	Destination Unreachable	0-15	Indicates that a packet could not reach its destination. Different codes specify the reason.
4	Source Quench	0	Deprecated. Previously used to indicate network congestion.
5	Redirect	0-3	Suggests a better route for the packet.
8	Echo Request	0	Used for ping tests to check connectivity.
9	Router Advertisement	0	Sent by routers to advertise their presence.
10	Router Solicitation	0	Sent by hosts to request router advertisements.
11	Time Exceeded	0-1	Packet exceeded its lifetime (TTL expired or reassembly timeout).
12	Parameter Problem	0-2	Packet contains an invalid header field.
13	Timestamp Request	0	Requests a timestamp from the destination.
14	Timestamp Reply	0	Response to a Timestamp Request.
15	Information Request	0	Deprecated. Previously used for address assignments.
16	Information Reply	0	Response to an Information Request.
17	Address Mask Request	0	Used to request the subnet mask of a network.
18	Address Mask Reply	0	Response to an Address Mask Request.

For the purpose of this reading pay attention to the Echo and Echo Reply messages, which have types 8 and 0 respectively.

How to use

First, you must start the docker containers. The repo includes two containers icmp-client and icmp-server, with a client and server application respectively. Docker will take care of installing the necessary tools and compiling both applications. See the docker-compose.yml.

docker compose up --build

Alternatively, you can run them separately:

docker compose run icmp-client
docker compose run icmp-server

Run client

We need to connect to the client container and start the client application.

docker exec -it icmp-client /bin/sh
bin/client icmp-server

The program will print a output similar to the following:

~/code # bin/client icmp-server
21 bytes from 172.22.0.3: pid=921, icmp_type=echo reply, icmp_seq=0, data=hello from client, time:590μs
21 bytes from 172.22.0.3: pid=921, icmp_type=echo reply, icmp_seq=1, data=hello from client, time:506μs
21 bytes from 172.22.0.3: pid=921, icmp_type=echo reply, icmp_seq=2, data=hello from client, time:505μs

But, who is responding to the message if we have not started the server yet?

An ICMP request does not require any specialized server software to handle it, because the operating system running on the machine has built-in functionality for handling ICMP messages. Specifically, the OS is set up to recognize and respond to ICMP Echo Requests by automatically sending back an ICMP Echo Reply. This built-in mechanism is part of the network stack in the operating system, which manages network communication. The client determines the latency by calculating the elapsed time between the echo and the echo reply.

However, it does not mean that we can send ICMP requests to any server. Routers and firewalls could prevent or filter those messages. Others will limit the rate to prevent flooding.

Note: I used microseconds instead of milliseconds just for convenience. The elapsed time is very short in this case to use milliseconds.

Run server

We can run our own ICMP handler if we want. Our handler will process the packet and send it back to the sender, but changing the type to echo reply. We are not covering other special cases in this article.

Now that the machines are running, connect to the server:

docker exec -it icmp-server /bin/sh
bin/server

Once you start the client you will see a similar output:

~/code # bin/server
21 bytes from 172.22.0.2: pid=927, icmp_type=echo, icmp_seq=0, data=hello from client
21 bytes from 172.22.0.2: pid=927, icmp_type=echo, icmp_seq=1, data=hello from client
21 bytes from 172.22.0.2: pid=927, icmp_type=echo, icmp_seq=2, data=hello from client

~/code # bin/client icmp-server
21 bytes from 172.22.0.3: pid=927, icmp_type=echo reply, icmp_seq=0, data=hello from client, time:1017μs
21 bytes from 172.22.0.3: pid=927, icmp_type=echo reply, icmp_seq=0, data=hello from client, time:660μs
21 bytes from 172.22.0.3: pid=927, icmp_type=echo reply, icmp_seq=1, data=hello from client, time:525μs

As you can see, the server is receiving the packets and echoing the message back to the sender. The same way as before the client can determine the latency by calculating the elapsed time between the echo and the echo reply. Also note that send request is of type echo and the answer from the server is of type echo reply.

Implementation details

If you want to see the full code, navigate to the Github repository.

Here is the code to send Echo requests to a server:

func Ping(host string, attempts int, delay time.Duration) error {

    raddr, err := net.ResolveIPAddr("ip4", host)
    if err != nil {
        return fmt.Errorf("failed to resolve target address: %w", err)
    }

    conn, err := net.DialIP("ip4:icmp", nil, raddr)
    if err != nil {
        return fmt.Errorf("failed to create ICMP connection: %w", err)
    }
    defer conn.Close()

    data := []byte("hello from client")
    for i := 0; i < attempts; i++ {
        echoReq := icmp.Message{
            Type: ipv4.ICMPTypeEcho,
            Code: 0,
            Body: &icmp.Echo{
                ID:   os.Getpid() & 0xffff,
                Seq:  i,
                Data: data[:],
            },
        }

        msgBytes, err := echoReq.Marshal(nil)

        if err != nil {
            return fmt.Errorf("failed to marshal ICMP message: %w", err)
        }

        if err := conn.SetReadDeadline(time.Now().Add(1 * time.Second)); err != nil {
            return fmt.Errorf("failed to set read deadline: %w", err)
        }

        timeStart := time.Now()
        if _, err := conn.Write(msgBytes); err != nil {
            return fmt.Errorf("failed to send ICMP message: %w", err)
        }

        resp := make([]byte, 512)
        n, peer, err := conn.ReadFrom(resp)
        timeEnd := time.Now()
        if err != nil {
            return fmt.Errorf("failed to read ICMP response: %w", err)
        }

        parsedMsg, err := icmp.ParseMessage(1, resp[:n])
        if err != nil {
            return fmt.Errorf("failed to parse ICMP message: %w", err)
        }

        echoType := parsedMsg.Type
        body := parsedMsg.Body.(*icmp.Echo)
        proto := parsedMsg.Type.Protocol()

        switch parsedMsg.Type {
        case ipv4.ICMPTypeEchoReply:
            elapsed := timeEnd.Sub(timeStart)
            fmt.Printf("%d bytes from %s: pid=%d, icmp_type=%v, icmp_seq=%d, data=%s, time:%dμs\n", body.Len(proto), peer, body.ID, echoType, body.Seq, string(body.Data), elapsed.Microseconds())
        default:
            fmt.Printf("received unexpected message from %s: pid=%d, icmp_type=%v, icmp_seq=%d, data=%s\n", peer, body.ID, echoType, body.Seq, string(body.Data))
        }
        time.Sleep(1 * time.Second)
    }
    return nil
}

Additionally, this is the code for receiving those ICMP requests and sending them back to the sender:

func Pong() error {
    addr := "0.0.0.0"
    raddr, err := net.ResolveIPAddr("ip4", addr)

    if err != nil {
        return fmt.Errorf("error resolving ip: %w", err)
    }

    conn, err := net.ListenIP("ip4:icmp", raddr)

    if err != nil {
        return fmt.Errorf("error listening package: %w", err)
    }

    buf := make([]byte, 512)

    for {
        numRead, from, _ := conn.ReadFrom(buf)

        echoReq, err := icmp.ParseMessage(1, buf[:numRead])

        if err != nil {
            fmt.Printf("error parsing message: %s", err)
            continue
        }

        body := echoReq.Body.(*icmp.Echo)
        echoType := echoReq.Type
        proto := echoReq.Type.Protocol()
        if echoType != ipv4.ICMPTypeEcho {
            fmt.Printf("received unexpected message from %s: pid=%d, icmp_type=%v, icmp_seq=%d, data=%s\n", from, body.ID, echoType, body.Seq, string(body.Data))
            continue
        }

        fmt.Printf("%d bytes from %s: pid=%d, icmp_type=%v, icmp_seq=%d, data=%s\n", body.Len(proto), from, body.ID, echoType, body.Seq, string(body.Data))

        reply := icmp.Message{
            Type: ipv4.ICMPTypeEchoReply,
            Code: 0,
            Body: &icmp.Echo{
                ID:   body.ID,
                Seq:  body.Seq,
                Data: body.Data,
            },
        }

        replyBytes, err := reply.Marshal(nil)

        if err != nil {
            fmt.Printf("error serializing reply: %s", err)
            continue
        }

        _, err = conn.WriteTo(replyBytes, from)

        if err != nil {
            fmt.Printf("error sending reply: %s", err)
            continue
        }
    }
}

Conclusions

The Internet Control Message Protocol (ICMP) is a fundamental part of networking, providing useful information regarding the communication between devices. The concept of "ping," often associated with online gaming and other real-time applications, relies heavily on ICMP Echo requests and replies to determine network latency. Understanding and using ICMP correctly can help diagnose network issues, measure latency, and optimize connectivity in both personal and professional environments.

Bibliography

GeeksForGeeks - 2024 - Internet Control Message Protocol (ICMP)
golang.org - 2024 - icmp-example
RFC-792 - 2024 - ICMP
stackoverflow - 2024 - Implementing ICMP ping in Go

Messed up a git rebase? Now What?

José David Ureña Torres — Sun, 08 Sep 2024 15:14:34 +0000

Introduction

Git rebase is a powerful tool that can help you to move or combine one or more commits onto a new base commit, rewriting the project history to make your branch appear as it was created from another commit. This helps maintain a cleaner and more linear history. In this article, we will cover the fundamentals of rebasing branches, explore some common pitfalls, provide real life examples, and suggestions of how to deal with them.

Keep in mind that this article focuses on Git, not on collaborative tools for Git repositories like Github or Gitlab, except for common concepts such as code approvals, pull requests, remote repository, that we will mention as they come up.

That said, let's get started.

Git Rebase: The basics

Why would someone do a rebase if there is a git merge command? There are scenarios when rebasing is more useful than merging. For instance, let's say you have been working on a new feature on a separate branch for some time. During that time, the master branch has progressed with new commits that your working branch does not have, because it was created before those new commits were added.
This situation is very common when you work with other people. Also, rebasing helps to maintain a cleaner history of the project and facilitates troubleshooting when a bug appears in a feature that was previously working fine.

I personally prefer the interactive tool for doing a rebase. If you are not familiarized with it, you can use it by adding the -i or --interactive flag, e.g. git rebase -i master to rebase your working branch with master.

With the interactive mode, I take the opportunity to squash my commits into the few as possible. What do I mean by that? If you are working on a small or medium-sized ticket, it is often unnecessary to keep all the commits you made. Instead you can combine them into a single commit and give it a descriptive name.

For example:

// Prefer a single commit on the master branch
e184504 (HEAD -> master) feature A

// instead of separate commits that belong to the same feature
e754500 (HEAD -> master) add Z
714fb43 add Y
8147fb0 add X

The interactive tool allows to perform different operations during the rebase like pick, drop, reword or squash. If you want to learn more about this interactive mode, check this resource: rewriting history

Imagine that you are working on a project where the master branch has two commits:

e754500 (HEAD -> master) add About page
714fb43 add Login page

Then, you created a feature-1 branch from master branch and worked on it. Here is the history for the new branch:

3ac2d3d (HEAD -> feature-1) fix bug with contact service
0a298d8 add fix bug in contact form
f91cc77 add Contact page
e754500 add About page
714fb43 add Login page

After you got the necessary approvals on Github, the branch is ready to be merged. However, you found that other team members are being merging changes into the master branch while you were working on feature-1.

cdf9f3f (HEAD -> master) add Home page // feature-1 does not have this commit
902add0 add Blog page // feature-1 does not have this commit
e754500 add About page
714fb43 add Login page

This is where git rebase comes into play. First you need to pull the latest changes from master, by checking out master and executing git pull origin master. Then, if you type git rebase master a normal rebase you can make your working branch to look similar to this:

c1fbb22 (HEAD -> feature-1) fix bug with contact service
85d4677 add fix bug in contact form
701da95 add Contact page
cdf9f3f (master) add Home page
902add0 add Blog page
e754500 add About page
714fb43 add Login page

Note: Github and Gitlab have options for doing this in the same website.

With the interactive mode you can use the squash option to combine your commits into a single commit. You can achieve it by changing the word pick for squash or the letter s:

pick c1fbb22 fix bug with contact service
squash 85d4677 add fix bug in contact form
squash 701da95 add Contact page

That will combine three commits from your working branch into a single commit:

fb8036f (HEAD -> feature-1) add Contact page
cdf9f3f (master) add Home page
902add0 add Blog page
e754500 add About page
714fb43 add Login page

Now you can merge your branch without any issues.

If you want to learn more about rebasing, I wrote other article some time ago: Guide to deeply understand merge rebase squash and cherry-pick.

Sometimes there will be conflicts during the rebase. When that happens, Git will ask you to resolve them first. If things go wrong during the rebase, you can always execute git rebase --abort to cancel the operation and start over. After you resolved all the conflicts, you can continue the process by typing git rebase --continue.

Now let's dive into a more complex situation when things have gone really wrong.

Undoing a Committed Rebase

What happens if, for some reason, you dropped a commit that should have not been deleted, or squashed a commit that you did not wanted to squash. One situation where this might happen is when you need to refactor a service or a class to prepare it for your new feature, and you were not expecting it.

Ideally, you should create a separate branch for this refactor and open a Pull Request, so that your co-workers or team lead can review the refactor first, avoiding unnecessary noise to the feature. I encourage you to do that whenever possible.

However, let's say that you decided to keep the refactor in the same branch. If you make a mistake like dropping or squashing the wrong commits, a git revert will not help you, because they will not appear in the history anymore.

Let's break this down with an example:

You have been working on a new feature for a project. During the development, you encountered a blocker, some legacy code that needs to be refactored to support your feature. Let's say that you kept it in the same branch, with the plan to create a separate branch for it later, once your feature is finished.

Your history looks like this:

d600d8a (HEAD -> feature-1) fix bugs related to feature 1
37356d2 initial implementation of feature 1
92829c9 (refactor) prepare codebase for feature 1
fb8036f other commit

You are ready to push your changes to the remote repository. But first, you need to squash your commits, to maintain your history clean. I know that it does not make much sense if the branch has just two commits. But in a real scenario there could be a lot of commits in your working branch.

Thus, you decided to rebase your branch to fetch the latest changes from master and take the opportunity to squash your commits during the process, giving them a descriptive name. You did this by typing git rebase -i master.

Here is the output of that command:

pick 92829c9 (refactor) prepare codebase for feature 1
pick 37356d2 initial implementation for feature 1
pick d600d8a fix bugs related to feature 1

However, by accident you told Git to combine your feature with the refactor:

pick 92829c9 (refactor) prepare codebase for feature 1
squash 37356d2 initial implementation for feature 1 # this one should have remained as "pick"
squash d600d8a fix bugs related to feature 1

After saving your changes with :wq, git allows you to change the commit name if you want. Now the history looks like this:

404824f (HEAD -> feature-1) add feature 1
fb8036f other commit

And then, you noticed your mistake. The refactor commit is gone. The three commits were combined, and you only intended to combine the last two. You can always pull your changes from the remote repository and restore your branch, if and only if you pushed your changes previous to rebase your branch. To make it worse, let's say you pushed your changes with git push -f. Now we are in trouble.

However, we can still try one more thing.

Note: Be careful. If you pull the remote branch after a rebase you can loose your progress on the local branch, specially if you did not pushed your changes previous to the rebase.

Git Reflog

Something interesting about Git is that it is difficult to really delete things. Even if the deleted commits are no longer visible in the history, there is a change that we can still access them by checking the reference logs, also known as reflog.

The reflog records almost everything that you do in the local repository, and provides more information than commands like git log. We can access the reflog by typing git reflog show. Here are part of my reflogs:

404824f (HEAD -> feature-1) HEAD@{0}: rebase (finish): returning to refs/heads/feature-1
404824f (HEAD -> feature-1) HEAD@{1}: rebase (squash): add feature 1
df8d688 HEAD@{2}: rebase (squash): # This is a combination of 2 commits
92829c9 HEAD@{3}: rebase (start): checkout master
d600d8a HEAD@{4}: commit: fix bugs related to feature 1
37356d2 HEAD@{5}: commit: initial implementation for feature 1
92829c9 HEAD@{6}: commit: (refactor) prepare codebase for feature 1
fb8036f HEAD@{7}: checkout: moving from master to feature-1
...

Based on that, we can infer that the rebase occurred between HEAD and HEAD@{2}. Additionally, HEAD@{3}, HEAD@{4}, HEAD@{5} and HEAD@{6} points to the changes before the rebase. You can safely check out any of those commits. Just keep in mind that any checkout operation also generates entries in the reflog, which means the HEAD@{n} reference will change for a particular commit. You can checkout the commit by its hash as well.

Note: According to the official documentation, the reflog has a default expiration of 90 days.

After inspected those commits with git checkout, it seems that the best candidate is HEAD@{4} (d600d8a). Let's restore our branch.

There are multiple ways to do it. One approach would be to delete the working branch and recreate it from d600d8a by typing:

git checkout d600d8a
git branch -D feature-1
git checkout -b feature-1

Alternatively, you can reset your working branch with git reset --soft d600d8a. I personally prefer this approach, but use whatever works better for your specific case.

After the git reset, here are the history logs:

d600d8a (HEAD -> feature-1) fix bugs related to feature 1
37356d2 initial implementation for feature 1
92829c9 (refactor) prepare codebase for feature 1
fb8036f other commit

That is it. Now we have the commits previous to the rebase, and since we learned from our mistakes, we proceed to push our changes to the remote repository before even start the rebase. After that, we can safely rebase the working branch and do what we need to do. In this case, we wanted to squash the last two commits and keep the refactor as a separate commit. Now the history looks like this:

d600d8a (HEAD -> feature-1) add feature 1
92829c9 (refactor) prepare codebase for feature 1
fb8036f other commit

Finally, once we are 100% sure that the rebase was successful we can push the changes to the remote repository.

Conclusion

Git is a powerful and versatile tool, but its flexibility can lead to human errors. It is important to know those common errors, how to prevent them and deal with them if necessary.

In this article we learned how to combine commits and rewrite the log history using git rebase. We also explored some examples where things can go wrong and introduced git reflog as an method to restore deleted commits in our working branch.

Bibliography

Atlassian | 2024 | Ref And The Reflog
Atlassian | 2024 | Rewriting History
Git Reference | 2024 | Git Reflog
Git Reference | 2024 | Git Tools Rewriting History
Jodaut | 2023 | Beyong-the-basics-guide-to-deeply-understand-merge-rebase-squash-and-cherry-pick

Beyond the Basics. Guide to Deeply Understand Merge, Rebase, Squash, and Cherry Pick - When to Use Them With Real-World Examples

José David Ureña Torres — Fri, 28 Jul 2023 15:00:04 +0000

Introduction
Merge or rebase, which should you use?
- Merge approach
- Rebase approach
  - Cannot push my changes after a rebase
Cherry pick
- Is Cherry Pick a bad practice?
Git squash
- Squash with merge
- Squash with rebase
- What happens if I messed up a branch when rebasing or merging?
Conclusions
Bibliography

Introduction

Git is a powerful tool that helps developers work together on software projects. Created by Linus Torvalds in 2005, it has become one of the most widely used version control systems in the software development industry.

If you're new to Git, you might find it challenging to find information about when and how to use certain commands with real-world examples. Many tutorials only give you the commands, which might be enough for experienced developers but not for beginners.

Imagine you work in a small company with a few developers and no established version control practices. It's up to you to improve the development process, but there are no senior developers to guide you. Knowing Git deeply can make a big difference for you and your colleagues.

In this article, we'll explore fundamental Git commands to combine branches effectively and how to respond to different situations. We will cover the main differences between merging and rebasing, and when should you use each of them. Also, how to use cherry pick to add specific commits into one or more branches, and why you should combine related commits into a single one to keep your branch clean. Finally, we'll discuss how to prevent some common issues when working with branches.

If you're completely new to Git, you can still read this article, but some concepts might be unclear. Feel free to come back later once you have the basics down. That being said, let's get started!

Merge or rebase, which should you use?

Choosing between merge and rebase can be tough and usually depends on your company's practices. If you have the choice, knowing the pros and cons of each method is vital for making the right decision based on your company's needs.

Git merge combines changes from one branch into another, creating a new commit with the merged changes. On the other hand, Git rebase rewrites the history of one branch onto another, adding your commits on top of the updated branch. To put it simply, it temporarily removes your commits, updates the branch from the specified one, and then adds your commits at the top of the history.

Now, let's explore each method in more detail.

Consider a main branch with the commit history below:

> git checkout main
> git log --oneline
0a9c4e8 (HEAD -> main) feature3
26c4d90 feature2
8bb8ce9 feature1

These codes at the beginning of every line are called commit hashes or commit IDs, and they serve as unique identifiers associated to every commit created. A commit ID consists of a 40-digit long SHA-hash (a hash algorithm), which can be abbreviated to a shorter 7-digit version.

Continuing with the example, you have a ticket assigned and need to create a feature4 branch with git branch feature4 and git checkout feature4. You develop your feature, add tests, and now it’s ready to be merged to main. It has the following commit history:

> git checkout feature4
> git log --oneline
dd01e58 (HEAD -> feature4) (fix) feature4
55b4a8b feature4
0a9c4e8 feature3
26c4d90 feature2
8bb8ce9 feature1

Therefore, you go to Github and create a new Pull Request, but you find that main was updated while you where working on your branch. In other words, the main branch now is different from the one you created your branch. It has a new commit.

> git checkout main
> git pull origin main
> git log --oneline
cf0e10a (HEAD -> main) feature5
0a9c4e8 feature3
26c4d90 feature2
8bb8ce9 feature1

However, conflicts can arise when the destination branch has new commits that modify the same sections you were working on your branch. In such cases, you have an alternative: instead of merging feature4 into main (main ← feature4), you can update feature4 with the changes from main (main → feature4). To achieve this, you have two options: merge or rebase.

Merge approach

If you merge main into feature4, then Git will create a new commit containing the changes from main and will add them at the top of the working tree. Let’s see it in action.

git checkout feature4
git merge main

Git will open the editor you set up, which is typically Vim by default. You will see something like this:

Merge branch 'main' into feature4
# Please enter a commit message to explain why this merge is necessary,
# especially if it merges an updated upstream into a topic branch.
#
# Lines starting with '#' will be ignored, and an empty message aborts
# the commit.

For simplicity, I'll keep this default commit message. To save it, press ESC+:wq. If you're unfamiliar with Vim commands, consider taking a brief tutorial on YouTube or your preferred platform.

Now check the commit history again:

> git log --oneline
96f49c0 (HEAD -> feature4) Merge branch 'main' into feature4
cf0e10a (main) feature5
dd01e58 (fix) feature4
55b4a8b feature4
0a9c4e8 feature3
26c4d90 feature2
8bb8ce9 feature1

Notice that there are two new commits, but cf0e10a is the only one that was on main . Where did this other commit come from?

When you merge a branch, Git adds the commits from the source branch and creates a new commit that combines the changes from both branches. If there are no conflicts, this commit will be automatically created. However, if conflicts occur, you must resolve them and then create the commit manually.

Remember to update your local main branch before the merge. If you don’t do it, there will be nothing to merge into feature4 .

Now you can push your changes with git push origin feature4 and then merge it into main. For simplicity let’s do a local git merge to main:

> git checkout main
> git merge feature4
> git log --oneline
96f49c0 (HEAD -> main, feature4) Merge branch 'main' into feature4
cf0e10a feature5
dd01e58 (fix) feature4
55b4a8b feature4
0a9c4e8 feature3
26c4d90 feature2
8bb8ce9 feature1

Notice this (HEAD -> main, feature4). It means that main and feature4 now have the same commit at the HEAD. In other words, both branches point to the same commit.

Rebase approach

As mentioned before, a rebase is slightly different. It basically rewrites the history of a branch, adding your commits on top of the updated branch. But, what does “rewrite” mean in this context? It means to modify the original commit history by creating new commits with different hashes and add them to the commit history, but not necessarily at the top. After that, the old commit history is replaced by the new one. Let’s see an example:

> git checkout main
> git pull origin main
> git checkout feature4
> git rebase main
> git log --oneline
0c847bd (HEAD -> feature4) (fix) feature4
b86b56d feature4
cf0e10a (main) feature5
0a9c4e8 feature3
26c4d90 feature2
8bb8ce9 feature1

As you can see cf0e10a was added before you commits, and that commit was created after the ones from feature4. With Git rebase, your changes are added to the top of the history without extra commits like a merge. However, you may notice that the hashes of your two commits from feature4 are not the same as before, while the commits from main remain unchanged. Weird, right?

dd01e58 changed to 0c847bd

55b4a8b changed to b86b56d

This is a particularity of git rebase, as it rewrites the git history, creating new commits with your changes and discarding the originals. As a result, the new commits are not the same as the original ones. The good news is that the original dates and author information remain unchanged. This is the reason why some companies prefer not to rebase branches and instead opt for using merge, as rebasing alters the past commits.

Now that feature4 is updated, you can perform a normal merge into main. Remember, that in the real life, you would need to push your changes and create a Pull Request.

> git checkout main
> git merge feature4
> git log --oneline
0c847bd (HEAD -> main, feature4) (fix) feature4
b86b56d feature4
cf0e10a feature5
0a9c4e8 feature3
26c4d90 feature2
8bb8ce9 feature1

This time, the commit hashes between both branches are identical, and there is no extra commit. However, it's worth noting that Git may behave differently on platforms like GitLab and GitHub, where additional commits might be added.

My personal recommendation is to avoid using rebase on main or other critical branches to preserve the original hashes for better traceability. Instead, use it for temporary branches derived from another branch, like feature branches. If your branch is going to be deleted after a merge, then you can rebase it. For main is not the case. Once your commits were added to main you should not override them.

Also, rebase will prevent a long series of commits from being scattered in the commit history and cause a lot of noise in your branch.

Cannot push my changes after a rebase

In real environments, you don't merge into main directly. In fact, you probably won't be able to merge to the main branch on GitHub either. Instead, you'll need to create a Pull Request (or Merge Request if you are using GitLab) to be able to merge your changes. Assuming you've already created your branch and pushed it to the remote repository, when you proceed to push your changes with git push origin <branch> you could get an error similar to this one:

Your branch and 'origin/<branch>' have diverged,
    ...
  (use "git pull" to merge the remote branch into yours)
nothing to commit, working tree clean

If you force a git pull, you could lose your changes. You can solve it by executing this command: git push -f origin <branch>. Keep in mind that git push -f will override the upstream branch, so be careful with this. Later in this reading, we will explore ways to prevent lost of information.

Cherry pick

Imagine that you work for a company with three different branches under development: main, legacy-v1, and legacy-v2. The naming convention for branches is just for educational purposes.

The QA team has discovered an issue with an old feature present in all three branches under development. After fixing the issue, you need to bring the changes into all three branches. But how should you do it? Copy the code to all the other branches? That's probably not a good idea.

The next logical solution that comes to mind is to create a new Pull Request to merge these changes into the other branches. However, there is a problem: the other two branches might differ significantly from the main branch, resulting in numerous conflicts. In such cases, it could be impossible to merge them cleanly. This is where cherry-pick comes in.

This command allows you to append arbitrary commits from a branch to the HEAD of another branch, without the need for a full merge.

The syntax is the following:

git cherry-pick <commit-sha>

First, you need to find the commit that you want to backport to the other branches. You can use git log for that.

> git log --oneline                 
8d84e7b (HEAD -> main) (fix) feature 1
222159b feature 4
32d540d feature 3
718f740 feature 2
78662d0 feature 1

ℹ️ The --oneline flag is just minimal information. I usually recommend to use git log --stat to get full information of your commits.

Suppose that 8d84e7b (short version) or 8d84e7b6bf5ed8a4fee96dfa820e544567542785 is the commit hash that you want to backport to the other two branches.

You only have to switch to the other branch an execute the command.

> git checkout legacy-v1
> git cherry-pick 8d84e7b6bf5ed8a4fee96dfa820e544567542785

Now the commit has been appended successfully.

> git log --oneline
0c41007 (HEAD -> legacy-v1) (fix) feature 1
9689a1c feature 5
222159b feature 4
32d540d feature 3
718f740 feature 2
78662d0 feature 1

Repeat the process for legacy-v2.

> git checkout legacy-v2
> git cherry-pick 8d84e7b6bf5ed8a4fee96dfa820e544567542785
> git log --oneline
73deb0b (HEAD -> legacy-v2) (fix) feature 1
0b67041 feature 6
222159b feature 4
32d540d feature 3
718f740 feature 2
78662d0 feature 1

Notice the commit hashes of legacy-v1 and legacy-v2 are different from main. This is because during the cherry-pick, Git created a new commit from 8d84e7b and appended it to the destination branch.

Is Cherry Pick a bad practice?

Some developers, especially the most purist Git users, will not recommend using this command. They will prefer a merge over a cherry-pick. But probably, they do not believe the cherry-pick command to be bad per se, but how you use it can be bad for your repository.

I like this comment that was posted on a StackOverflow question:

The SHA1 identifier of a commit identifies it not just in and of itself but also in relation to all other commits that precede it. This offers you a guarantee that the state of the repository at a given SHA1 is identical across all clones. There is (in theory) no chance that someone has done what looks like the same change but is actually corrupting or hijacking your repository. You can cherry-pick in individual changes and they are likely the same, but you have no guarantee. (As a minor secondary issue the new cherry-picked commits will take up extra space if someone else cherry-picks in the same commit again, as they will both be present in the history even if your working copies end up being identical.) (Git Cherry-pick vs Merge Workflow, 2017)

In my opinion, this command is very useful when you have to maintain different branches under development that differ a lot between them, and merging is not an option anymore. If you can merge without problems, then do it, but if not, don't worry and just use cherry pick.

However, you have to be very careful if your commit is complex, modifies different files, and causes merge conflicts. It's recommended to have good testing coverage that helps you detect quickly if something breaks.

Git squash

The last command that we are going to cover in this article is git squash. This command can help you maintain your main branch clean if you created a lot of small commits.

Imagine that your just finished to work in a feature in notice that your branch has a lot of commits with smalls changes made during the days you worked on that feature. For you they make sense, but for your colleagues, they are just random commits. Let’s see and example of a group of commits created during the development of payment feature.

b86b56d Add initial HTML structure for payment checkout page.
a5e392f Implement basic CSS styles for payment form.
cf872e2 Fix alignment issues in the payment summary section.
0c31e2d Add credit card input validation for card number and expiration date.
d6c59a7 Implement UI for selecting payment method (credit card, PayPal, etc.).
e8af221 Add CSS transitions for a smoother payment form experience.
3e987b8 Fix bug with PayPal payment option not showing up in the UI.
95c67f2 Update button styles for the payment confirmation step.
713bd64 Integrate backend API for processing payment requests.
2d344ef Update success message for completed payments.

You probably will be agree with me that, in the long run, those small related commits are not important seen them individually. In this case you should use a git squash. This command allows to combine a group of commits in a single commit with a more meaningful name your your team. Those commits can be summarize into a single descriptive commit as follows:

b86b56d Implement new payment checkout UI with improved user experience, payment method selection, validation, and backend integration.

It sounds better, right? It’s very common that companies try to have a single commit per feature in their main branch, because it’s easier to rollback if something goes wrong, or add tags to their new releases.

Let’s see another example.

You have two branches: main and feature4. The following is the log history of both branches:

> git checkout main
> git log --oneline
d303a7a (HEAD -> main) feature5
0a9c4e8 feature3
26c4d90 feature2
8bb8ce9 feature1
> git checkout feature4
> git log --oneline
0c847bd (HEAD -> feature4) (fix) feature4
b86b56d feature4
d303a7a (main) feature5
0a9c4e8 feature3
26c4d90 feature2
8bb8ce9 feature1

In this example the feature4 branch only have two commits, but they could be a lot. Also, note that the last commit seems to refer to some kind of fix or improvement made to the code or suggestion you received from another coworker.

Maybe these commits messages may not be relevant in the big picture of the product. The only thing that matters is that the feature4 is ready to be merged into main. To squash these commits you can use rebase or merge.

The two branches have the following commit history:

> git checkout main
> git log --oneline
159678e (HEAD -> main) feature6
d303a7a feature5
0a9c4e8 feature3
26c4d90 feature2
8bb8ce9 feature1
> git checkout feature4
0c847bd (HEAD -> feature4) (fix) feature4
b86b56d feature4
d303a7a (main) feature5
0a9c4e8 feature3
26c4d90 feature2
8bb8ce9 feature1

Squash with merge

This command is quite similar to the traditional merge process. The only difference is that you may add the —squash flag. This will add the changes from feature4 to the index (equivalent to if you just have written all the changes and executed git add ). Then, you have to commit the changes with a meaningful name to finalize the merge process. See the example below:

> git checkout main
> git merge --squash feature4
> git commit -m "feature4"

If you have merge conflicts you have to solve them before committing.

After the merge, a new commit containing the other two commits will have been created as follows:

> git log --oneline
cda90a7 (HEAD -> main) feature4
159678e feature6
d303a7a feature5
0a9c4e8 feature3
26c4d90 feature2
8bb8ce9 feature1

Notice that the commit was added after feature6 , although it was added after the feature4 last commit.

Squash with rebase

To do this you need to add a -i flag in your rebase as follow:

> git checkout feature4
> git rebase -i main

Git will open Vim. You should see something similar to this:

pick b86b56d feature4
pick 0c847bd (fix) feature4

# Rebase 159678e..0c847bd onto 159678e (2 commands)
#
# Commands:
# p, pick <commit> = use commit
# r, reword <commit> = use commit, but edit the commit message
# e, edit <commit> = use commit, but stop for amending
# s, squash <commit> = use commit, but meld into previous commit
# f, fixup [-C | -c] <commit> = like "squash" but keep only the previous
#                    commit's log message, unless -C is used, in which case
#                    keep only this commit's message; -c is same as -C but
#                    opens the editor
# x, exec <command> = run command (the rest of the line) using shell
# b, break = stop here (continue rebase later with 'git rebase --continue')
# d, drop <commit> = remove commit
# l, label <label> = label current HEAD with a name
# t, reset <label> = reset HEAD to a label
# m, merge [-C <commit> | -c <commit>] <label> [# <oneline>]
#         create a merge commit using the original merge commit's
#         message (or the oneline, if no original merge commit was
#         specified); use -c <commit> to reword the commit message
# u, update-ref <ref> = track a placeholder for the <ref> to be updated
#                       to this position in the new commits. The <ref> is
#                       updated at the end of the rebase
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#

Don’t panic. All these lines starting with # are just instructions of what can you do with this utility. The only one that matter for us right now is the squash option, or its abbreviation s. You have to replace the word “pick” starting with the second one from the top as follows::

pick b86b56d feature4
squash 0c847bd (fix) feature4

All the lines with squash will be combine into the previous one that has the pick word.

To save this changes press ESC + :wq . Git will open Vim again, but this name asking you for a commit message.

# This is a combination of 2 commits.
# This is the 1st commit message:

feature4

# This is the commit message #2:

(fix) feature4

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# Date:      Sat Jul 15 09:11:55 2023 -0600
#
# interactive rebase in progress; onto 159678e
# Last commands done (2 commands done):
#    pick b86b56d feature4
#    squash 0c847bd (fix) feature4
# No commands remaining.
# You are currently rebasing branch 'feature4' on '159678e'.
#
# Changes to be committed:
#       new file:   file2.txt
#

Add a meaningful name. In this case, for the purpose of this tutorial, feature4 is enough. You can delete all the lines by pressing DD or D<number-of-lines-to-delete>D .

After that, press ESC+:wq again to save the changes.

> git log --oneline
62b8724 (HEAD -> feature4) feature4
159678e (main) feature6
d303a7a feature5
0a9c4e8 feature3
26c4d90 feature2
8bb8ce9 feature1

As you can see, Git created a new commit and added it at the top of the log history. Notice that the commit hash is not the same as the one with you specified the pick option that would contain all the commits with the squash option:

b86b56d (before the rebase)

62b8724 (after the rebase)

That is because Git cannot reuse a hash code containing different changes. In this case, Git is forced to use a different hash and save all the changes as a new commit. By requiring an initial "pick" commit, Git establishes a clear reference point for the rebase operation. This ensures that the rebase proceeds in an organized and predictable manner, without any ambiguity about the order of commits.

Now you can switch to main and perform a regular merge as follows:

> git checkout main
> git merge feature4
> git log --oneline
62b8724 (HEAD -> main, feature4) feature4
159678e feature6
d303a7a feature5
0a9c4e8 feature3
26c4d90 feature2
8bb8ce9 feature1

As it is a regular merge, the 62b8724 commit was kept. This also means that main and feature4 now point to the same commit.

What happens if I messed up a branch when rebasing or merging?

The best way handle these situations is with prevention. If you are going to make important changes in your code base, it is recommended to do it in your local computer if possible. In that case, if you damage your branch, you can always download it again from the remote repository as follows:

> git checkout main
> git branch -D feature4 # delete the feature4 branch
> git checkout origin feature4

Another alternative that you have is to backup the branches that will be affected before executing risky commands. Continuing with the previous example, you can backup your main and feature4 branches before any operation that can affect them irreversibly.

This option is preferred if you are planning to push your changes to your remote repository, because if you execute a git push -f origin <branch> you will override the remote branches and could lose information if you don’t know what you are doing. Backup your branches is as simple as follows and can save you a lot of headaches:

> git branch feature4-backup feature4

By doing that, if you delete or damage accidentally your local and remote branches, you can execute this commands to restore the branch:

> git branch feature4 feature4-backup
> git push --set-upstream origin feature4

A third alternative is to save the commit hash instead of backup the entire branch. Since the nature of Git, you can still access commits by hash even if you deleted the branch which they belonged. Consider a branch called feature8 with the following commits:

> git checkout feature8
> git log --oneline
407f3e2 (HEAD -> feature8) feature8
309129e (fix) feature7
9ec402e feature7
62b8724 feature4
159678e feature6
d303a7a feature5
0a9c4e8 feature3
26c4d90 feature2
8bb8ce9 feature1

You can save these commits in a file you can access later. In this way, if you delete your branch you can restore from the commit. Imagine that you delete some commits by accident using this command:

> git reset --hard HEAD~3
> git push -f origin feature8

Now the log history looks like this:

62b8724 (HEAD -> feature8) feature4
159678e feature6
d303a7a feature5
0a9c4e8 feature3
26c4d90 feature2
8bb8ce9 feature1

Although, it seems that you lost all your work you still have a chance to restore it with the commit hash that you previously saved. Try with these commands:

git checkout feature8
git merge 407f3e2

Now you commit history is restored.

> git log --oneline
407f3e2 (HEAD -> main) feature8
309129e (fix) feature7
9ec402e feature7
62b8724 feature4
159678e feature6
d303a7a feature5
0a9c4e8 feature3
26c4d90 feature2
8bb8ce9 feature1

Don’t forger to push your changes to the remote repository to repair your remote branch as well.

ℹ️ There are more techniques like git reflog. However, they are not covered in this tutorial.

Conclusions

Throughout this article, we have explored essential Git commands and their practical applications. We covered the fundamental differences between merging, rebasing, cherry-picking and squashing.

It's important to choose the right approach depending on your team's practices and the specific project needs. By combining deep knowledge of Git with careful consideration of the project's requirements, you can improve significantly the quality of the development workflow. Each approach has its use cases, and knowing when to use them can save you from future problems.

This tutorial was just a collection of lessons and real-world examples that I would have love to read when I was learning about Git. Having readings like this one would have made my learning process more robust, providing more context not only on how but also when should I use all these commands that I learned.

Bibliography

Git - Book | 2023 | Git Docs

Stack Overflow | 2013 | Git cherry pick vs rebase

Stack Overflow | 2017 | Git Cherry-pick vs Merge Workflow

Atlassian Bitbucket | 2023 | Merging vs. Rebasing

Atlassian Bitbucket | 2023 | Git Cherry Pick

Firebase Learning: Key Considerations to Keep in Mind

José David Ureña Torres — Wed, 08 Feb 2023 06:48:09 +0000

Introduction

Firebase is a suite of cloud-based tools and services on Google Cloud Platform for application development. It offers hosting, authentication, storage, and databases that can be easily integrated into your app. One of its most popular tools is called Firestore, a key-value non-relational database. That means that uses structures similar to JSON to store information.

During my professional experience with Firebase and Google Cloud, I encountered challenges with optimizing and securing applications. To help others overcome these difficulties, I have compiled some key insights that I wish I had known from the start. Whether you're a beginner or an experienced developer, the concepts outlined in this article are essential for a successful learning journey with these technologies.

Security Rules

Firebase documentation does not emphasize enough the importance of Security Rules, especially for those just starting to integrate Firebase into their projects. If you do not properly implement security rules in your production application it can have severe consequences. Without proper security, anyone can potentially modify your database through API access, such as through Bash or Powershell.

It is crucial to design your Firebase Security Rules before writing any code. If Security Rules are added at the end of the development process, you may be faced with the issue of accumulated technical debt and security vulnerabilities, which can be both time-consuming and costly to resolve.

Security Rules should be considered a critical component of database design and should be discussed throughout the entire project, especially in the early stages. It's more efficient to revise and make changes to a draft on paper or a Jamboard than to retroactively fix a production implementation affecting numerous users.

There are several patterns for controlling access to your application, including:

Authenticated-only access
Content-owner-only access
Granular access control
Functional access control

Authenticated-only access

You can restrict reading access to a collection of only signed-in users:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match posts/{document=**} {
      allow read: if request.auth != null
            allow write: if false
    }
  }
}

Content-owner-only access

Also, you can implement a content-owner-only access pattern. In this way, users can access only their own documents, that is, the documents that have the same uid as the user.

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /user/{userId}/{documents=**} {
      allow read, write: if request.auth != null && request.auth.uid == userId
    }
  }
}

Granular control access

Another option is to add more granular rules to restrict access depending on the specific operation.

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /posts/{documents=**} {
      allow read: if request.auth != null && request.auth.uid && get(/databases/$(database)/documents/users/$(request.auth.uid)).data.role == "Reader"
            allow create, update: if request.auth != null if get(/databases/$(database)/documents/users/$(request.auth.uid)).data.role == "Writer"
            allow delete: if request.auth != null if get(/databases/$(database)/documents/users/$(request.auth.uid)).data.role == "Admin"
    }
  }
}

In this example, the user only can read a post if he has reading access, and only can create and update a post if he is a writer. Also, only an Admin can delete content inside the posts collection.

Functional control access

If your project has a lot of duplicated code in your security rules, you can refactor it into functions and call those functions instead of copy and paste your rules.

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
        function isAuthenticated(){
            return request.auth != null
        }
        function isAdmin(){
            return isAuthenticated() && get(/databases/$(database)/documents/users/$(request.auth.uid)).data.role == "Admin"
        }

    match /products/{documents=**} {
            allow read, write: if isAdmin()
    }
  }
}

Note: You have to keep in mind that {documents=**} means that it includes all the subcollections inside the products collection.

The Local Emulator Suite

It would be helpful if Firebase's documentation emphasized how important it is to use this tool, especially for those who use Firebase Functions. However, it doesn't seem like the documentation talks about it very much. There are entries on their website related to the Emulator Suite, but it feels a little messy sometimes. It took me months to understand that I could take advantage of that Emulator Suite and how to use it properly.

This tool lets you test your projects on your own computer without affecting the real services. The local emulators support Firestore, Realtime Database, Functions, Storage, Authentication, and PubSubs.

Testing your security rules and storage rules with the local emulators before you publish them to Google Cloud can help you find problems early. Plus, it can help you save money because fewer deploys mean fewer charges. Keeping all your rules in one place also makes it easier to keep track of them.

You can see the official documentation to learn more about the Local Emulator Suite

Optimizations for performance and scalability

It might seem like a waste of time to focus on scalability and performance at the start of a small project. This is correct, in a way. Engineers have to avoid over-engineering. However, it is important to have a solid understanding of algorithms and logic so you are prepared when the project grows and performance becomes an issue. Otherwise, you may end up having to spend a lot of time and money fixing slow execution time or high memory consumption. To be efficient, you should learn techniques for writing more efficient Firebase Functions, like how to delete big collections or update many documents with complicated conditions.

How to delete large collections

Some collections can grow to millions of documents, and deleting documents inside of them can be a computation-intensive task. The examples below come from the official Firebase documentation. These show the recommended way of handling this type of task.

async function deleteCollection(db, collectionPath, batchSize) {
  const collectionRef = db.collection(collectionPath);
  const query = collectionRef.orderBy('__name__').limit(batchSize);

  return new Promise((resolve, reject) => {
    deleteQueryBatch(db, query, resolve).catch(reject);
  });
}

async function deleteQueryBatch(db, query, resolve) {
  const snapshot = await query.get();

  const batchSize = snapshot.size;
  if (batchSize === 0) {
    // When there are no documents left, we are done
    resolve();
    return;
  }

  // Delete documents in a batch
  const batch = db.batch();
  snapshot.docs.forEach((doc) => {
    batch.delete(doc.ref);
  });
  await batch.commit();

  // Recurse on the next process tick, to avoid
  // exploding the stack.
  process.nextTick(() => {
    deleteQueryBatch(db, query, resolve);
  });
}

If you're working with big files and running into processing issues, one solution could be to give your function more resources, like extra RAM or a longer timeout.

exports.convertLargeFile = functions
    .runWith({
      // Ensure the function has enough memory and time
      // to process large files
      timeoutSeconds: 300,
      memory: "1GB",
    })
    .storage.object()
    .onFinalize((object) => {
      // Do some complicated things that take a lot of memory and time
    })

Enqueued Cloud Tasks

For time-consuming, resource-intensive, or bandwidth-limited tasks that need to run asynchronously, Google Cloud offers the possibility to enqueue functions with Cloud Tasks. You can control the number of attempts, backoff second, and the max of concurrent dispatches. The example below comes from the official documentation:

exports.backupApod = functions
    .runWith( {secrets: ["SOME_KEY"]})
    .tasks.taskQueue({
      retryConfig: {
        maxAttempts: 5,
        minBackoffSeconds: 60,
      },
      rateLimits: {
        maxConcurrentDispatches: 6,
      },
    }).onDispatch(async (data) => {
        //your complex task
    })

exports.enqueueBackupTasks = functions.https.onRequest(
async (_request, response) => {
  const queue = getFunctions().taskQueue("backupApod");
  const enqueues = [];
  for (let i = 0; i <= 10; i += 1) {
    // Enqueue each task with i*60 seconds day. Our task queue function
    // should process ~1 task/min.
    const scheduleDelaySeconds = i * 60
    enqueues.push(
        queue.enqueue(
          { id: `task-${i}` },
          {
            scheduleDelaySeconds,
            dispatchDeadlineSeconds: 60 * 5 // 5 minutes
          },
        ),
    );
  }
  await Promise.all(enqueues);
  response.sendStatus(200);

});

Backups in Firebase

As far as I know, right now Google Cloud doesn't have a way to automatically backup Firestore. I use BackupFire to do it for me, but you can also write a solution using Firebase Functions. Just keep in mind that when you restore a backup, Firebase tries to merge it with the original database, not overwrite it. This can have important consequences. Consider this example:

There are two customers:

User A, uid: z1V5scLfVPX7YD8fRCFRhhRAwVN2
User B, uid: Zk5olEuvZ1WokRrCqIN5gGaIu353

User A gained a gift card or discount code and it was saved in a subcollection inside the user document.

users/z1V5scLfVPX7YD8fRCFRhhRAwVN2/discountCodes/dGn5OxSEPohqpZbIyLmCjqVEiwz2

{
    code: 'dGn5OxSEPohqpZbIyLmCjqVEiwz2',
    expirationDate: '2023-01-18T18:34:33.565Z',
    isAGift: false
}

The app allows users to transfer codes to others. User A transferred the code to User B

users/z1V5scLfVPX7YD8fRCFRhhRAwVN2/discountCodes/dGn5OxSEPohqpZbIyLmCjqVEiwz2

{
    code: 'dGn5OxSEPohqpZbIyLmCjqVEiwz2',
    expirationDate: '2023-01-18T18:34:33.565Z',
    isAGift: true
}

However, a backup from the previous day had to be restored due to an emergency. Upon checking, there were inconsistencies in the database. Both User A and User B now have the same discount code.

users/z1V5scLfVPX7YD8fRCFRhhRAwVN2/discoutCodes/dGn5OxSEPohqpZbIyLmCjqVEiwz2

{
    code: 'dGn5OxSEPohqpZbIyLmCjqVEiwz2',
    expirationDate: '2023-01-18T18:34:33.565Z',
    isAGift: false
}

users/z1V5scLfVPX7YD8fRCFRhhRAwVN2/discoutCodes/dGn5OxSEPohqpZbIyLmCjqVEiwz2

{
    code: 'dGn5OxSEPohqpZbIyLmCjqVEiwz2',
    expirationDate: '2023-01-18T18:34:33.565Z',
    isAGift: true
}

To avoid these issues in Firestore, you can create a script that verifies the correct documents and removes the duplicates. Another solution is to design your database in a way that avoids documents that can be transferred, for example, with a collection in the root path of your database.

discoutCodes/dGn5OxSEPohqpZbIyLmCjqVEiwz2

{
    code: 'dGn5OxSEPohqpZbIyLmCjqVEiwz2',
    expirationDate: '2023-01-18T18:34:33.565Z',
    isAGift: true
    createdBy: z1V5scLfVPX7YD8fRCFRhhRAwVN2
    owner: Zk5olEuvZ1WokRrCqIN5gGaIu353
}

In this way, there is only one code available and transfer it to another user means just editing the owner field inside this document. Keep in mind that this is a specific problem related to the key-value internal structure of Firestore and may not occur in other databases.

Conclusions

In conclusion, it is important to consider scalability and performance efficiency in the early stages when designing a project, especially with Firebase; but without over-engineering. This can save time and resources in the long run. Additionally, it is essential to have a backup plan for Firestore, as restoring a backup can sometimes result in inconsistencies. To mitigate these issues, one can either use a third-party service or create their own solution based on Firebase Functions. It is also crucial to design the database in such a way as to avoid transferable subcollections that could lead to document duplications.

Bibliography

Backup Fire | 2022 | BackupFire Official Site

Firebase Documentation | 2022 | Emulator Suite

Firebase Documentation | 2022 | Security Rules Basics

Firebase Documentation | 2022 | Security Rules Getting Started

Google Developers | 2022 | Task Functions

Google Developers | 2022 | Manage Functions

Google Cloud | 2002 | Delete a Firestore collection

Python type checking with Visual Studio Code

José David Ureña Torres — Mon, 18 Apr 2022 14:46:17 +0000

When working in a team, it's important to establish a set of best practices that allows all the developers, old and new, to be productive while reducing the number of bugs and time required to understand a block of code.

If you are working with other developers and need to be explicit with function signatures and variables, using static typed languages can be a good choice for your project. Since Python 3, you can add static types, but the IDE or code editor does not display any errors if you assign the incorrect value to a variable.

In this tutorial, we will set up Python to behave like a static typed languages. We will configure real-time static types checking in VS Code for Python projects. I prefer that the setup only show errors when you explicitly add the type of variable or function parameter in your code, while still allowing for normal variables.

Configure Venv

Venv is a Python built-in tool for creating a virtual environment that isolates the project dependencies, so you can install dependencies only for that specific project without affecting other projects in your computer.

Windows setup

py -m venv venv

.\venv\Scripts\activate

Linux or MacOS setup

python3 -m venv venv

venv/bin/activate

Install Mypy

Next, install Mypy. This package checks types in your Python code and define a set of rules according to your needs.

Setup

pip install mypy

Add Gitlens extension

Install GitLens extension for VS Code.

Next, add these settings in your local settings.json.

{
  "python.linting.mypyEnabled": true,
  "python.linting.mypyArgs": [
    "--ignore-missing-imports",
    "--follow-imports=silent",
    "--show-column-numbers",
    "--allow-untyped-defs",
    "--allow-subclassing-any",
    "--allow-untyped-calls",
    "--strict"
  ]
}

--strict: This option enables strict type checking. Although, it can be over strict in some cases. When you have existing code, and you don't want to change it because you know it works. Furthermore, so many errors can be distracting for developers. The flags below customize this strict mode to make it less strict.

--ignore-missing-imports: Suppresses error messages about unresolved imports. In Django, some imports can raise a warning without this flag. Only use it if your project contains warnings that you know aren't a real problem.

--follow-imports=silent: Turn off type checking in imported modules. Many libraries were not developed with static type checking in mind, so it's better to suppress type checking in imported modules.

--show-column-numbers: Shows column numbers in error messages.

--allow-untyped-defs: Suppress errors if you have non-typed functions in Python.

--allow-subclassing-any: Permits subclassing a value of type Any. Some frameworks can throw these errors with Mypy, therefore if you have them, add this line.

--allow-untyped-calls: Allows you to invoke non-typed functions in your code.

You should not have any issues by adding it gradually to your project with this setup. Mypy has a lot of options, feel free to try other configurations for your specific case.

First simple example

Create a example.py in the root of your project.
Add this code (yo lo dejaria hasta aqui) into that file.

def sum(n1: int, n2: int) -> int:
    return n1 + n2


def sub(n1, n2):
    return n1-n2


result = sum(1, 2.5)
print(result)
result = sub(1, 2.5)
print(result)

As you can see in the image below, a lot of errors are displayed because sum expect two int parameters, but is given a float value. However, sub lacks a type definition, no errors are displayed.

This is really powerful. Errors are displayed only in functions and variables that are required, and it will not interfere with your existing codebase.

Django example

Let's try in a more complex scenario using a Django project. Django is a framework to build web applications. See the docs here. But don't worry, there is no need to know it to follow this section.

Keep in mind that Django is not a static typed Framework. Using only the --strict mode in settings.json will result in a lot of errors. If you configured the settings.json file as previously described, you shouldn't have any issues.

To create a new project:

    pip install django
    django-admin startproject myapp
    cd myapp
    py manage.py startapp clients

Now let's add some code that generates errors in your client.views.py

from django.http import JsonResponse
from django.shortcuts import render
from urllib.request import Request
from venv import create


def createGreeting(name: str) -> str:
    return f'Hello {name}!!!!'


def getPower(n):
    x = 42 == 'no'
    return n**2


def index(request):
    message = createGreeting(3, 'asdf')
    message = createGreeting(100)
    message: int = 'asdf'
    message: str = 1234
    n = getPower('asdf')
    return JsonResponse({'message': message})

Despite many errors appeared in clients.urls.py, the project is still running. Django imports and default code are fine because it will only check variables and functions that you manually type.

Conclusions

During this tutorial, we learned how to configure Visual Studio Code to check static types in Python projects and display errors in development.

Remember that you can be strict as needed, but be careful. Here is a list of considerations to keep in mind:

Pros:

If working in a team it reduces cognitive effort to understand how to use a piece of code.
Increases productivity because the code documents itself.
Improves code documentation and readability.
Reduce redundant tests
Constant real-time feedback.
Reduces development errors
It is customizable.

Cons:

Increases the complexity of your project.
Many Python developers don't like typing code.
It is impossible to be certain that a function will return what it says.
The less restrictive your configuration is, the fewer errors are displayed.

Use it to develop new libraries and complex modules that must be thoroughly tested. It's not recommended for trying to add static typed to third-party libraries or legacy codebases (unless strictly necessary), because it could cause a lot of problems and time spent. Focus on the new code to write. Feel free to try with different configurations. In the long run, you and your team will be grateful for incorporating this tool into the workflow.

Bibliography

Tushar Sadhwani - 2021 - The Comprehensive Guide to mypy

Kracekumar - 2021 - Type Check Your Django Application

DEV Community: José David Ureña Torres

How SSH Works—and How It Breaks: A Practical Guide to Secure Remote Access

Introduction

Why hostnames and IP addresses cannot be trusted for SSH authentication

Common Attack Vectors

DNS poisoning

Hosts file poisoning

Network-level and routing attacks

Host Key Verification: How SSH Verifies the Server's Identity

When the Fingerprints Don't Match

But What Is a Fingerprint in the First Place?

Common Questions and Misconceptions

If I see a host key verification error, am I under a man-in-the-middle attack?

Why would anyone intentionally disable host key verification?

What if I’m connecting via VPN or a private network?

What about automation tools like Ansible?

Do testing environments really need this level of caution?

Conclusion

Bibliography

Linux Without Fanboyism: An Honest Developer’s Perspective

Introduction

My Linux Journey

The good parts

The appeal of Linux

Highly customizable

Familiar if you use Linux at work

Docker containers run natively on Linux

Scripting and automation

The trade-offs

Things can break

Learning curve

Hardware support

Software compatibility

Choosing the right hardware for you

Choosing the right Linux distribution for you

Choosing the right desktop environment for you

A few common questions

Conclusion

Bibliography

Building A Minimal SSH Server in Go

Why An SSH Server?

Overview of SSH Channel Types and Requests

SSH Channel Types

Channel Requests

Project Scope and Technical Approach

Features

Authentication

SSH server configuration

Access control

Concurrency

Testing

Language

Coding phase

High-Level Steps

Challenges

Source code

Bibliography

Understanding ICMP: How to Send and Receive ICMP Messages in Go

Introduction

Why Go?

Understanding ICMP

ICMP packet structure

List of ICMP Messages

How to use

Run client

Run server

Implementation details

Conclusions

Bibliography

Messed up a git rebase? Now What?

Introduction

Git Rebase: The basics

Undoing a Committed Rebase

Git Reflog

Conclusion

Bibliography

Beyond the Basics. Guide to Deeply Understand Merge, Rebase, Squash, and Cherry Pick - When to Use Them With Real-World Examples

Table of Contents

Introduction

Merge or rebase, which should you use?