Text of increment.com › containers › exploring-open-source-codebase-docker-cli as Styx crawled it on Nov 18, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Exploring an open-source codebase: Digging into the Docker CLI – Increment

I’ve been around the block a few times when it comes to open source, dabbling and delving into projects of all shapes and sizes and seeking out opportunities to learn. When I’m exploring a new codebase, I follow a framework I like to call “open-source archeology.” It’s a set of steps that allows me to understand the processes and concepts associated with a project before I start contributing. Using the codebase of the Docker CLI , a set of open-source tools for interacting with Docker over the command line, as a guiding example, let’s walk through these steps together.

Starting the dig Before looking at any of the code in the repo, I’ll sift through a project’s open issues to get a sense of the common bugs and feature gaps. This step will also help identify the key maintainers and suss out how different concepts in the project intersect with each other. After skimming the issues, I’ll pick one to steer my exploration: Instead of trying to understand everything at once, I’ll select a few things to try to understand in the context of that particular issue.

There are two basic levels to understanding a piece of software: understanding enough to know how it works, and understanding enough to know how it works and how it can be modified or improved. In my experience, reading through a codebase with the intent of making a change is the best way to gain that deeper level of understanding. Because the Docker CLI is a fairly well-scoped and mature project, the feature requests tend to address advanced workflows in Docker.

I’ve chosen an open issue (at the time of writing) that adds support for reading a Docker config from multiple locations. Now, it’s time to get hands-on with the code. Excavating the source These days, instead of using git clone to grab a local copy of the codebase, I like to lean on GitHub’s command line application, which lets you grab a clone of a repository on your local machine with a single command: $ gh repo clone docker/cli I’ve long been a fan of the pen-and-paper approach to exploring codebases.

Browsing through files, I’ll create lists and draw concept maps to decipher patterns within the code. Recently, I started taking digital notes and leveraging the CodeTour VS Code extension, which allows me to create annotated code walkthroughs. I can add descriptions to relevant directories and files, arrange them in a meaningful order, then walk back through them. It’s like creating a museum tour for code. Some people prefer debugging as a way to understand codebases.

This is a totally valid approach, but I find setting up a debuggable scenario is a shade more involved than annotating the codebase. Plus, with a lot of modern editor technologies, understanding the connections between different pieces of code is fairly effortless. You can delve pretty deep into a project without needing to involve a debugging scenario. Deciphering the code Now that we’ve got cloning squared away, we can talk about how to uncover the connections between different files.

In the case of the Docker CLI, most of the actual CLI’s logic is implemented under a top-level CLI directory. It contains subdirectories that deal with particular concepts, like interfacing with the Docker registry or defining the functions associated with each command in the CLI. For this particular change, I’ll start by locating the configuration-related code paths in the codebase. Most of the logic is stored under the (aptly named) config directory.

The logic associated with reading the configuration file into an in-memory format lives in one source file and in an entrypoint LoadDefaultConfigFile method, which is called when the CLI object is instantiated. A lot of this exploration relies on identifying the places code is likely to live based on file names. It just goes to show how important naming is! Getting a sense of the code organization is one of the first steps for reading code—as with an essay outline, it provides a map to guide further exploration.

The inception of a feature is a key part of its story, helping to reveal why it was implemented in the first place. Once we have a basic understanding of the codebase, we can start filling in gaps and adding layers to our knowledge. I recommend examining the most public-facing APIs—in this case, the invocations a user would issue to the Docker CLI—and working backward from there. Alternatively, you can start by identifying the key types defined in a codebase and then fan out to determine where they’re instantiated or invoked.

There’s also a historical element to understanding a codebase, which brings us to another handy code exploration tool: git blame . It allows you to explore the changesets associated with a particular piece of code, and can help pinpoint when particular features were added. The inception of a feature is a key part of its story, helping to reveal why it was implemented in the first place. Reviewing the pull request associated with a change can also provide valuable context into how it came to be.

I’ve learned a lot about how projects work and how to write good code by reading the reviews associated with a change. Looking beyond the dig You’ve now built a solid foundation for the next steps in your open-source journey: triaging issues, troubleshooting them with users, and making code changes. I list code changes last for a reason: An understanding of the concepts allows you to contribute to open source in so many more ways.

It’s easy to assume that contributing to open source is mostly about code, but I’d argue that it’s really about the ideas behind the code. There’s plenty to do with an open-source project before writing a single line. Exploring a codebase is a fascinating blend of archeology, history, and literature that sets you up to contribute to a project with deeper comprehension and confidence. About the author Safia Abdalla is a software engineer working on open-source technologies at Microsoft and an open-source maintainer on the nteract project.

When she’s not working on open source, she enjoys writing and running. @captainsafia Artwork by Mercedes Bazan behance.net/mercedesbazan Topics Guides & Best Practices Buy the print edition Visit the Increment Store to purchase print issues. Store Continue Reading 9 Open Source Safia Abdalla Beyond maintenance A consideration of how human-oriented investments are vital to a project’s long-term health. 15 Remote Safia Abdalla Open-source excursions: A journey into remote record keeping A new column exploring engineering topics through an open-source lens.

16 Reliability Safia Abdalla Open-source excursions: Optimizing for operational resiliency Documentation, automation, and a little sharing-is-caring can help OSS projects maintain their uptime. 18 Mobile Safia Abdalla Open-source excursions: Views from the mobile stack Exploring the emerging possibilities for open-source mobile hardware and software. 19 Planning Safia Abdalla Open-source excursions: The poetry of planning Reflections on the value of a planning process that emphasizes transparency, empathy, and the people behind the products.

13 Frontend Safia Abdalla On composable, modular frontends A look at using composable design for frontend components to help build scalable and maintainable frontend systems. 9 Open Source Juan Pablo Buriticá A punk rock guide to conference organizing DIY lessons from planning JSConf Colombia for anyone, anywhere who wants to plan accessible, sustainable developer events. 9 Open Source James Turnbull More productive Git Tips for acquiring Git super powers.

17 Containers Liz Rice Containers in the keep Like the fortifications of a medieval castle, the multilayered practice of defense in depth can help protect your containers—no moats, drawbridges, or dragons required. Explore Topics Learn Something New Scaling & Growth Ask an Expert Interviews & Surveys Guides & Best Practices Essays & Opinion Workplace & Cultur

The rest of this page is on the live site.