Initial commit

Author: ianthomas23

.gitignore

@@ -0,0 +1,2 @@
+build/
+__pycache__/

.pytest.ini

@@ -0,0 +1,3 @@
+[pytest]
+testpaths =
+    test

LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, QuantStack.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -0,0 +1,27 @@
+# git2cpp
+
+This is a C++ wrapper of [libgit2](https://libgit2.org/) to provide a command-line interface (CLI)
+to `git` functionality. The intended use is in WebAssembly in-browser terminals (see
+[cockle](https://github.com/jupyterlite/cockle) and
+[JupyterLite terminal](https://github.com/jupyterlite/terminal) projects) but it can be compiled and
+used on any POSIX-compliant system.
+
+See `overview.md` for further details.
+
+Developer's workflow using `micromamba` to manage the dependencies:
+
+```bash
+micromamba create -f dev-environment.yml
+micromamba activate git2cpp-dev
+meson setup build
+cd build
+meson compile
+```
+
+The `git2cpp` executable can then be run, e.g. `./git2cpp -v`.
+
+The CLI is tested using `python`. From the top-level directory:
+
+```bash
+pytest -v
+```

dev-environment.yml

@@ -0,0 +1,10 @@
+name: git2cpp-dev
+channels:
+  - conda-forge
+dependencies:
+  - cli11
+  - libgit2
+  - meson
+  - pkg-config
+  - python
+  - pytest

meson.build

@@ -0,0 +1,23 @@
+project(
+  'git2cpp',
+  'cpp',
+  default_options: [
+    'cpp_std=c++20',
+    #'werror=true',
+  ],
+  license: 'BSD-3-Clause',
+)
+
+cli11_dep = dependency('CLI11')
+libgit2_dep = dependency('libgit2')
+
+subdir('src')
+
+executable(
+  'git2cpp',
+  src_files,
+  dependencies: [
+    cli11_dep,
+    libgit2_dep,
+  ],
+)

overview.md

@@ -0,0 +1,45 @@
+# Overview
+
+The motivation is to provide a `git`-like command-line interface (CLI) to the
+[JupyterLite terminal](https://github.com/jupyterlite/terminal) but allow most of the development
+work to occur outside of a WebAssembly toolchain for ease.
+
+[libgit2](https://libgit2.org/) is a portable pure C implementation of `git` core functionality to
+allow library access rather than a CLI. There are many different programming language wrappers for
+it. It does include some CLI functionality in the form of examples, but these are not of core
+interest to most maintainers and users of the library, and are therefore not complete.
+
+The idea here is to write a C++ wrapper to `libgit2` to provide a CLI, starting with simple `git`
+functionality and expanding the scope over time. All development work can occur on POSIX systems
+away from a WebAssembly toolchain, and the final step is to use
+[Emscripten-forge](https://emscripten-forge.org/) recipes to build it for
+[cockle](https://github.com/jupyterlite/cockle), just like other commands.
+
+There are two areas of functionality to be written in C++:
+1. Thin C++ wrappers of the various `libgit2` C objects to give automatical deallocation of
+   resources as necessary.
+2. `git` command and subcommand implementations using [CLI11](https://github.com/CLIUtils/CLI11)
+   for argument parsing, as it used in [mamba](https://github.com/mamba-org/mamba) for example.
+
+`libgit2` is well tested and well maintained, so we do not envisage unit testing of our C++
+wrappers. The testing is therefore of the CLI, and hence does not have to be performed in C++ but
+can use `python` or `node` or similar instead.
+
+We will ignore some aspects of `git` initially that are hard to implement in a single-thread
+WebAssembly runtime, such as opening an editor for `git rebase` and so on. Instead we will
+probably use a fairly simple sequence of prompts and accepting `stdin` inputs from the user, and
+work towards full integration with editors at a later date.
+
+The `git2cpp` name of the project and executable follow from `libgit2` which includes its own `git2`
+and hence it would not be sensible to duplicate that name. In a terminal in which this is the only
+`git` implementation available we would expect users to set up aliases so that the usual `git`
+command name can be used.
+
+The alternative approach which we have rejected would be to start with the `git` source code itself,
+and build that for WebAssembly. That would involve removing functionality such as starting new
+processes to open editors by patching the source code for the WebAssembly build. That approach would
+be a much less pleasant developer experience than the one proposed here, given that all work would
+have to occur using a WebAssembly toolchain.
+
+All design decisions here are subject to change based on who the main developers will be and their
+preferred tools, etc.

src/git_exception.cpp

@@ -0,0 +1,25 @@
+#include <git2.h>
+
+#include "git_exception.hpp"
+
+void throwIfError(int exitCode)
+{
+    if (exitCode < 0) {
+        throw GitException(git_error_last()->message, exitCode);
+    }
+}
+
+
+GitException::GitException(const std::string& message, int errorCode)
+    : _message(message), _errorCode(errorCode)
+{}
+
+int GitException::errorCode() const
+{
+    return _errorCode;
+}
+
+const char* GitException::what() const noexcept
+{
+    return _message.c_str();
+}

src/git_exception.hpp

@@ -0,0 +1,20 @@
+#pragma once
+
+#include <exception>
+#include <string>
+
+void throwIfError(int exitCode);
+
+class GitException : public std::exception
+{
+public:
+    GitException(const std::string& message, int errorCode);
+
+    int errorCode() const;
+
+    const char* what() const noexcept override;
+
+private:
+    std::string _message;
+    int _errorCode;
+};

src/main.cpp

@@ -0,0 +1,45 @@
+#include <CLI/CLI.hpp>
+#include <git2.h>  // For version number only
+#include <iostream>
+
+#include "git_exception.hpp"
+#include "version.hpp"
+#include "subcommand/init_subcommand.hpp"
+
+int main(int argc, char** argv)
+{
+    int exitCode = 0;
+    try
+    {
+        CLI::App app{"Git using C++ wrapper of libgit2"};
+
+        // Top-level command options.
+        auto version = app.add_flag("-v,--version", "Show version");
+
+        // Sub commands
+        InitSubcommand init(app);
+
+        app.parse(argc, argv);
+
+        if (version->count())
+        {
+            std::cout << "git2cpp version " << GIT2CPP_VERSION_STRING << " (libgit2 " << LIBGIT2_VERSION << ")" << std::endl;
+        }
+    }
+    catch (const CLI::Error& e)
+    {
+        std::cerr << e.what() << std::endl;
+        exitCode = 1;
+    }
+    catch (const GitException& e)
+    {
+        std::cerr << e.what() << std::endl;
+        exitCode = e.errorCode();
+    }
+    catch (std::exception& e) {
+        std::cerr << e.what() << std::endl;
+        exitCode = 1;
+    }
+
+    return exitCode;
+}

src/meson.build

@@ -0,0 +1,7 @@
+subdir('subcommand')
+subdir('wrapper')
+
+src_files = files([
+    'git_exception.cpp',
+    'main.cpp'
+]) + subcommand_files + wrapper_files

src/subcommand/base_subcommand.hpp

@@ -0,0 +1,16 @@
+#pragma once
+
+#include <CLI/CLI.hpp>
+
+class BaseSubcommand
+{
+public:
+    BaseSubcommand() = default;
+
+    virtual ~BaseSubcommand() = default;
+
+    BaseSubcommand(const BaseSubcommand&) = delete;
+    BaseSubcommand& operator=(const BaseSubcommand&) = delete;
+    BaseSubcommand(BaseSubcommand&&) = delete;
+    BaseSubcommand& operator=(BaseSubcommand&&) = delete;
+};

src/subcommand/init_subcommand.cpp

@@ -0,0 +1,19 @@
+#include "init_subcommand.hpp"
+
+//#include "../wrapper/repository_wrapper.hpp"
+
+InitSubcommand::InitSubcommand(CLI::App& app)
+{
+    auto *sub = app.add_subcommand("init", "Explanation of init here");
+
+    sub->add_flag("--bare", bare, "--- bare ---");
+
+    sub->callback([this]() { this->run(); });
+}
+
+void InitSubcommand::run()
+{
+    std::cout << "RUN " << bare << std::endl;
+    //RepositoryWrapper repo;
+    //repo.init(bare);
+}

src/subcommand/init_subcommand.hpp

@@ -0,0 +1,13 @@
+#pragma once
+
+#include "base_subcommand.hpp"
+
+class InitSubcommand : public BaseSubcommand
+{
+public:
+    InitSubcommand(CLI::App& app);
+    void run();
+
+private:
+    bool bare;
+};

src/subcommand/meson.build

@@ -0,0 +1,3 @@
+subcommand_files = files([
+  'init_subcommand.cpp',
+])

src/version.hpp

@@ -0,0 +1,12 @@
+#pragma once
+
+#define GIT2CPP_VERSION_MAJOR 0
+#define GIT2CPP_VERSION_MINOR 0
+#define GIT2CPP_VERSION_PATCH 1
+
+// e.g. ".rc0"
+#define GIT2CPP_VERSION_SUFFIX
+
+#define STR_HELPER(x) #x
+#define STR(x) STR_HELPER(x)
+#define GIT2CPP_VERSION_STRING (STR(GIT2CPP_VERSION_MAJOR) "." STR(GIT2CPP_VERSION_MINOR) "." STR(GIT2CPP_VERSION_PATCH) GIT2CPP_VERSION_SUFFIX)

src/wrapper/base_wrapper.cpp

@@ -0,0 +1,15 @@
+#include <git2.h>
+
+#include "../git_exception.hpp"
+#include "base_wrapper.hpp"
+
+BaseWrapper::BaseWrapper()
+{
+    // Fine to initialise libgit2 multiple times.
+    throwIfError(git_libgit2_init());
+}
+
+BaseWrapper::~BaseWrapper()
+{
+    git_libgit2_shutdown();
+}

src/wrapper/base_wrapper.hpp

@@ -0,0 +1,16 @@
+#pragma once
+
+#include <git2.h>
+
+class BaseWrapper
+{
+public:
+    BaseWrapper();
+
+    virtual ~BaseWrapper();
+
+    BaseWrapper(const BaseWrapper&) = delete;
+    BaseWrapper& operator=(const BaseWrapper&) = delete;
+    BaseWrapper(BaseWrapper&&) = delete;
+    BaseWrapper& operator=(BaseWrapper&&) = delete;
+};

src/wrapper/meson.build

@@ -0,0 +1,4 @@
+wrapper_files = files([
+  'base_wrapper.cpp',
+  'repository_wrapper.cpp',
+])

src/wrapper/repository_wrapper.cpp

@@ -0,0 +1,29 @@
+#include <iostream>
+#include <string>
+
+#include "../git_exception.hpp"
+#include "repository_wrapper.hpp"
+
+RepositoryWrapper::RepositoryWrapper()
+    : _repo(nullptr)
+{}
+
+RepositoryWrapper::~RepositoryWrapper()
+{
+    if (_repo != nullptr) {
+        git_repository_free(_repo);  // no return
+    }
+}
+
+void RepositoryWrapper::init(bool bare)
+{
+    std::cout << "repo init - start" << std::endl;
+
+    // what if it is already initialised???
+
+    // convert error code to exception
+    std::string path = "repo";
+    throwIfError(git_repository_init(&_repo, path.c_str(), bare));
+
+    std::cout << "repo init - end " << std::endl;
+}

src/wrapper/repository_wrapper.hpp

@@ -0,0 +1,16 @@
+#pragma once
+
+#include "base_wrapper.hpp"
+
+class RepositoryWrapper : public BaseWrapper
+{
+public:
+    RepositoryWrapper();
+
+    virtual ~RepositoryWrapper();
+
+    void init(bool bare);
+
+private:
+    git_repository *_repo;
+};