A115 Logo Dark A115 Logo Light

A115 is a London-based consultancy helping fast-growing businesses and scale-ups build sophisticated on-prem or cloud-based technology platforms when code quality matters.

We specialise in rapidly building, securing and scaling cloud-native greenfield platforms to add new capabilities or expand into new markets. With over 20 years' experience productionising experimental code and complex systems, A115 provides end-to-end services - from initial architecture and infrastructure design through development, deployment and maintenance. Leveraging expertise across industries and technologies like Python, SQL, AWS and Azure, A115 enables clients to launch innovative products faster while ensuring robustness, resilience and regulatory compliance.


Training and Consulting

Bookmark this page and check again soon for our personalised individual or team training packages and offers!

London, United Kingdom (HQ)


Git Archeology with iCODES

Navigate complex codebase Git histories with ease

When working on complex codebases, understanding the intricate history and the reason for things being the way they are can be daunting. Especially when multiple past contributors have left little to no context behind their commits. Our new Git archeology tool, iCODES (Intelligent Commit Ontology Distiller and Enhanced Search) revolutionises how developers interact with Git repositories. This article dives into how iCODES can be leveraged to perform advanced Git archeology tasks, making it simpler to retrieve valuable insights and maintain continuity in software projects.

Understanding iCODES: An Overview

What is Git Archeology?

Git archeology refers to the practice of delving deep into the commit history of a software repository to uncover insights about the evolution of the codebase, identify the causes of bugs, understand decision-making processes, and trace the lineage of specific code changes.

This analysis is crucial for maintaining and improving large, complex systems where multiple contributors work across different modules over time.

Key Features of iCODES

iCODES stands out as a pioneering tool in the field of Git archeology by harnessing the capabilities of large language models (LLMs) to analyze, index, and interpret commit histories. The tool provides a rich set of features designed to enhance the way developers interact with Git repositories:

  • Intelligent Commit Analysis: By leveraging GPT-powered models, iCODES analyzes commit messages, code changes, and the broader project context to derive a deeper understanding of each commit's intent and impact. This not only includes the extraction of technical details but also the contextual interpretation of why changes were made, helping to bridge the gap between raw code diffs and human-readable explanations.
  • Commit Indexing: iCODES builds an indexed database of commit insights using SQLite, allowing for efficient searching and exploration. This database serves as a centralized repository of knowledge about the codebase’s evolution, accessible through powerful querying mechanisms.
  • Free Text Queries: With iCODES, searching for relevant commits is simplified through the use of free text queries. Developers can filter results by various parameters such as author, file path, and date range, making it easier to locate specific commits without needing to comb through the entire Git log manually.

Installation and Setup

To get started with iCODES, developers need Python 3.11 or higher. The tool can be installed directly from PyPI using the command:

pip install icodes

Once installed, iCODES requires the configuration of an API key for the OpenAI LLM service, which it uses to power its commit analysis features. This setup primes the tool for its core functionalities, offering a streamlined workflow for Git archeology tasks.

export OPENAI_API_KEY="your-openai-key"

By default, iCODES uses the gpt-3.5-turbo model, for a reasonable cost / price balance. However, you can easily control which model the tool uses, e.g.:

export DEFAULT_MODEL="gpt-4-turbo"

In the following sections, we'll explore how to practically apply these features to inspect and index a Git repository, providing a hands-on guide to getting the most out of iCODES.

Getting Started with iCODES

Once iCODES is installed and configured, the first step is to understand how to effectively utilise its capabilities to inspect and index a Git repository. This section provides a hands-on guide to these initial processes, enhancing your ability to manage and analyse any codebase.

Inspecting a Repository

To begin inspecting a repository with iCODES, you need to target a specific repository on your system. Here's how you can start:

icodes inspect-repo /path/to/repo [--branch-name BRANCH_NAME]

Replace /path/to/repo with the path to your local Git repository. The --branch-name option allows you to specify which branch to inspect. If no branch is specified, iCODES defaults to the current branch. This command analyzes the latest commit on the specified branch, providing insights into the commit's content and context.

By default, the tool analyses the 10 latest commits and only outputs the LLM-summarised commit messages. You can adjust the number of commits with the `--n-commits` option. You can also add the `--detailed` option to get a full break-down of the LLM's interpretation of each change diff. E.g.:

icodes inspect-repo /path/to/repo --n-commits 5 --detailed

This command helps you see a detailed breakdown of the commit changes, interpretations of the commit messages, and any associated metadata that can offer insights into the development processes.

Building an Indexed Database

iCODES allows you to build an indexed database of commit insights, which facilitates efficient search and exploration. This is particularly useful in large repositories with extensive commit histories. To build an index, execute the following command:

icodes build-index /path/to/repo

This command processes the latest commits in the specified repository and constructs an SQLite database that stores all the extracted commit insights. By default, iCODES stores this database in a file named icodes.db located in the current directory. However, you can specify a different name or location for the database by setting the DATABASE_URL environment variable:

export DATABASE_URL="sqlite:///path/to/custom/icodes.db"

This flexibility allows you to manage multiple databases for different projects or contexts, enhancing the organisational aspect of your Git archeology tasks. Or you can keep the indexes of multiple related codebases in a single database.

Example Usage

Consider a scenario where you need to track down the origin of a particular feature introduced several months ago. By using iCODES, you can build an index and then quickly perform a targeted search for commits related to that feature:

icodes search "invoicing"

Under the hood, this searches both the summarised commit messages and the full detailed break-down the LLM generated.

This search might reveal all commits with messages relating to the implementation of the feature, who made those commits, and when - as well as the LLM's best guess as to the intent behind each change. It simplifies the process of tracing back the development steps and understanding the evolution of the feature.

By following these steps to inspect and index your Git repository, you can harness the full potential of iCODES to make your codebase more understandable and navigable. This capability is invaluable for maintaining continuity in projects with numerous past contributors and complex development histories.

Practical Scenarios and Use Cases for iCODES

iCODES is not just a tool for analysing commit histories; it's a robust solution for tackling various real-world challenges that developers face in large, evolving codebases. Here, we explore practical scenarios where iCODES can significantly enhance productivity and understanding.

Scenario: Resolving Bugs by Tracing Historical Changes

A common challenge for developers is tracking down the origin of a bug introduced into a software system. iCODES can streamline this process by allowing developers to perform targeted searches across the commit history.

Suppose a bug was reported affecting the PING authentication module of a web application. You can use iCODES to search for recent commits that touched relevant files or components:

icodes search "ping" --file "src/auth/login.js"

This query will retrieve a list of commits specifically related to this authentication module, helping you quickly identify potential commits that may have introduced the bug.

Scenario: Automating the Creation of Well-written Release Notes

Release notes are essential for documenting the changes in new software versions, providing users and stakeholders with clear information on updates, bug fixes, and new features. iCODES can be instrumental in automating and enhancing the creation of these notes by extracting commit messages over a specified period, ensuring that all relevant changes are included.

Assume you are preparing release notes for a monthly software update. You need to compile all changes made during the last month. With iCODES, you can specify a date range to fetch all commits made within that period by leaving the query empty to capture every commit:

icodes search "" --start-date "2024-01-01"

Or, if you're a real hacker and can't be bothered to type the actual date for the first of last month:

icodes search "" --start-date "$(date -d "$(date +%Y-%m-01) -1 month" +%Y-%m-%d)"

This command will return all commits from the start of last month, providing a comprehensive list that can be refined and formatted into detailed release notes. This approach ensures that no significant changes are omitted and that the release notes are accurate and thorough.

Using iCODES in this way not only saves time but also increases the accuracy of the release notes, making them more useful for users who need to understand the implications of new updates. It also supports a consistent narrative style in the documentation.

Scenario: Merging and Rebaselining Efforts in Large Teams

In projects with multiple developers, branches can diverge significantly, making merging a complicated process. iCODES can be used to analyse the differences and commonalities in commit histories between branches, facilitating smoother integration.

Before merging a feature branch back into the main branch, use iCODES to inspect commits specific to that branch to understand changes thoroughly:

icodes inspect-repo /path/to/repo --branch-name feature/complex-algorithm --detailed

Insights gained from this inspection can inform your merging strategy, ensuring that integrations are handled efficiently and with full context.

Future Enhancements and Community Contributions

As iCODES continues to evolve, the roadmap includes several exciting enhancements that promise to broaden its functionality and adaptability.

One of the most anticipated features is the integration of semantic search capabilities using embeddings with a PostgreSQL vector database. This advancement will allow users to perform even more nuanced and context-aware searches within their Git histories using plain language, greatly enhancing the tool's utility for complex queries and large datasets.

Further expanding its versatility, iCODES will soon support various LLM backends. This includes integration with Anthropic’s Claude API and the ability to run models locally from Hugging Face, provided the user has the necessary GPU resources. Such additions will cater to a wider range of user preferences and technical requirements, enabling more flexible and powerful commit analysis.

Developers are encouraged to contribute to its development, whether by adding new features, refining existing ones, or providing feedback on usage and performance. Community contributions ensure that iCODES remains a cutting-edge tool tailored to the real-world needs of modern software teams. Please use the GitHub Issues page of the project to submit new bug reports or feature requests (ideally with a corresponding Pull Request!)


iCODES represents a significant step forward in the field of Git archeology, combining the analytical power of LLMs with practical, user-friendly features. As developers incorporate iCODES into their workflows, they gain a deeper understanding of their codebases, enabling better decision-making and more efficient project management.

The future enhancements will further cement iCODES as an essential tool in the savvy developer's arsenal, ensuring that it remains at the forefront of technology for managing and understanding complex codebases.

Jordan Dimov is an experienced software consultant specializing in business process automation, Python code quality, cloud solutions, software engineering training and AI. With over 20 years in the industry, Jordan helps companies boost their productivity by building high-quality, scalable, bespoke software solutions.

Consulting some of the fastest growing brands in the UK and globally, the founder of A115 has a no-nonsense educational approach to modern enterprise software engineering.

Jordan's expertise spans a wide range of technologies and domains:

* Building cloud-based ETL data pipelines for industries like commodity trading and asset management
* Developing e-commerce platforms, online payment processing, and bespoke invoicing, billing, bookkeeping and accounting solutions
* Creating generative AI applications using Python, FastAPI, HuggingFace models, and vector databases
* Productionising code and optimizing software architecture for performance and reliability
* DevOps and infrastructure-as-code using AWS CDK, Azure, Terraform, and Kubernetes

Some of Jordan's notable projects include:

* A position and P&L visualization tool for Shell's trading desks, saving millions by improving efficiency
* An AWS-based platform for automating power trading auctions at Shell and LimeJump
* A high-throughput trading analytics platform for Centrica using Python, Kafka, and serverless tech
* Building multi-currency e-commerce and payments infrastructure for international expansion for a number of clients
* An innovative SMS parking payments system processing 100K+ transactions daily for the city of Sofia, Bulgaria

With strong communication skills, Jordan excels at understanding complex business needs, defining technical solutions, and leading teams to deliver results. He brings a focus on code quality, software security, and process optimization to every project.

Contact Jordan to discuss how he can help your company leverage technologies like Python, cloud platforms, and AI to solve business challenges and achieve your goals.

Python Training
Bespoke Software
Code quality
Case Studies
Industry Insights

Subscribe to the A115 weekly newsletter!

By subscribing you agree to our Privacy Policy