# CHANGELOG

## Version 0.25.0

* Update to `radicle-git-ext-0.10.0` [6422fd5](https://app.radicle.xyz/nodes/seed.radicle.xyz/rad:z6cFWeWpnZNHh9rUW8phgA3b5yGt/commits/6422fd580b1c9c96ba40620197e29d7b9fbe2824)

## Version 0.9.0

This release consists of a major rewrite of this crate. Its API is overall

simplified and is not compatible with the previous version (v0.8.0). The main

changes include:

- `Browser` is removed. Its methods are implemented directly with `Repository`.

- Git will be the only supported VCS. Any extension points for other VCSes were

removed.

- `Ref` and `RefScope` are removed. Re-use the `git-ref-format` crate and a new

`Glob` type for the refspec patterns.

- Added support of `Tree` and `Blob` that correspond to their definitions in

Git.

- Added two new traits `Revision` and `ToCommit` that make methods flexible and

still simple to use.

For more details, please check out the crate's documentation.

[package]

name = "radicle-surf"

description = "A code surfing library for Git repositories"

readme = "README.md"

version = "0.26.0"

authors = ["The Radicle Team <dev@radicle.xyz>"]

homepage.workspace = true

repository.workspace = true

edition.workspace = true

license.workspace = true

rust-version.workspace = true

include = [

    "**/*.rs",

    "Cargo.toml",

    "data/git-platinum.tgz",

]

[lib]

test = false

doctest = false

[features]

# NOTE: testing `test_submodule_failure` on GH actions

# is painful since it uses this specific repo and expects

# certain branches to be setup. So we use this feature flag

# to ignore the test on CI.

gh-actions = []

minicbor = ["radicle-git-ext/minicbor"]

serde = ["dep:serde", "url/serde"]

[dependencies]

base64 = "0.21"

log = "0.4"

nonempty = "0.9"

thiserror = "1.0"

url = "2.5.4"

[dependencies.git2]

version = "0.19"

default-features = false

features = ["vendored-libgit2"]

[dependencies.radicle-git-ext]

version = "0.11.0"

path = "../radicle-git-ext"

features = ["serde"]

[dependencies.radicle-std-ext]

version = "0.2.0"

path = "../radicle-std-ext"

[dependencies.serde]

version = "1"

features = ["serde_derive"]

optional = true

[build-dependencies]

anyhow = "1.0"

flate2 = "1.1"

tar = "0.4"

# Radicle Surfing 🏄

Thanks for wanting to contribute to `radicle-surf`!

## Building & Testing 🏗️

We try to make development as seemless as possible so we can get down to the real work. We supply

the toolchain via the `rust-toolchain` file, and the formatting rules `.rustmt.toml` file.

For the [Nix](https://nixos.org/) inclined there is a `default.nix` file to get all the necessary

dependencies and it also uses the `rust-toolchain` file to pin to that version of Rust.

You can build the project the usual way:

```

cargo build

```

To run all the tests:

```

cargo test

```

For the full list of checks that get executed in CI you can checkout the [ci/run](./ci/run) script.

If any of this _isn't_ working, then let's work through it together and get it Working on Your

Machine™.

## Structure 🏛️

The design of `radicle-surf` is to have an in-memory representation of a project's directory which

can be generated by a VCS's backend. The directory system is modeled under `file_system`, the VCS

functionality is naturally under `vcs`, and `diff` logic is held under `diff`.

```

src/

├── diff

├── file_system

└── vcs

```

## Testing & Documentation 📚

We ensure that the crate is well documented. `cargo clippy` will argue with you anytime a public

facing piece of the library is undocumented. We should always provide an explanation of what

something is or does, and also provide examples to allow our users to get up and running as quick

and easy as possible.

When writing documentation we should try provide one or two examples (if they make sense). This

provides us with some simple unit tests as well as something our users can copy and paste for ease

of development.

If more tests are needed then we should add them under `mod tests` in the relevant module. We strive

to find properties of our programs so that we can use tools like `proptest` to extensively prove our

programs are correct. As well as this, we add unit tests to esnure the examples in our heads are

correct, and testing out the ergonomics of our API first-hand.

## CI files 🤖

Our CI infrastructure runs on Buildkite. The build process is run for every commit which is pushed

to GitHub.

All relevant configuration can be found here:

```

radicle-surf/.buildkite/

├── docker

│   ├── build

│   │   └── Dockerfile

│   └── rust-nightly

│       └── Dockerfile

└── pipeline.yaml

```

## Releases 📅

TODO: Once we get the API into a good shape we will keep track of releases via a `CHANGELOG.md` and

tag the releases via `git tag`.

# radicle-surf

A code surfing library for Git repositories 🏄‍♀️🏄‍♂️

Welcome to `radicle-surf`!

`radicle-surf` is a library to describe a Git repository as a file system. It

aims to provide an easy-to-use API to browse a repository via the concept of

files and directories for any given revision. It also allows the user to diff

any two different revisions.

One of the use cases would be to create a web GUI for interacting with a Git

repository (thinking GitHub, GitLab or similar systems).

## Contributing

To get started on contributing you can check out our [developing guide](../DEVELOPMENT.md), and also

our [LICENSE](../LICENSE) file.

## The Community

Join our community disccussions at [radicle.community](https://radicle.community)!

use std::{

    env, fs,

    fs::File,

    io,

    path::{Path, PathBuf},

};

use anyhow::Context as _;

use flate2::read::GzDecoder;

use tar::Archive;

enum Command {

    Build(PathBuf),

    Publish(PathBuf),

}

impl Command {

    fn new() -> io::Result<Self> {

        let current = env::current_dir()?;

        Ok(if current.ends_with("radicle-surf") {

            Self::Build(current)

        } else {

            Self::Publish(PathBuf::from(

                env::var("OUT_DIR").map_err(io::Error::other)?,

            ))

        })

    }

    fn target(&self) -> PathBuf {

        match self {

            Self::Build(path) => path.join("data"),

            Self::Publish(path) => path.join("data"),

        }

    }

}

fn main() {

    let target = Command::new()

        .expect("could not determine the cargo command")

        .target();

    let git_platinum_tarball = "./data/git-platinum.tgz";

    unpack(git_platinum_tarball, target).expect("Failed to unpack git-platinum");

    println!("cargo:rerun-if-changed={git_platinum_tarball}");

}

fn unpack(archive_path: impl AsRef<Path>, target: impl AsRef<Path>) -> anyhow::Result<()> {

    let content = target.as_ref().join("git-platinum");

    if content.exists() {

        fs::remove_dir_all(content).context("attempting to remove git-platinum")?;

    }

    let archive_path = archive_path.as_ref();

    let tar_gz = File::open(archive_path).context(format!(

        "attempting to open file: {}",

        archive_path.display()

    ))?;

    let tar = GzDecoder::new(tar_gz);

    let mut archive = Archive::new(tar);

    archive.unpack(target).context("attempting to unpack")?;

    Ok(())

}

# Design Documentation

In this document we will describe the design of `radicle-surf`. The design of the system will rely

heavily on [denotational design](todo) and use Haskell syntax (because types are easy to reason about, I'm sorry).

`radicle-surf` is a system to describe a file-system in a VCS world. We have the concept of files and directories,

but these objects can change over time while people iterate on them. Thus, it is a file-system within history and

we, the user, are viewing the file-system at a particular snapshot. Alongside this, we will wish to take two snapshots

and view their differences.

The stream of consciousness that gave birth to this document started with thinking how the user would interact with

the system, identifying the key components. This is captured in [User Flow](#user-flow). From there we found nouns that

represent objects in our system and verbs that represent functions over those objects. This iteratively informed us as

to what other actions we would need to supply. We would occassionally look at [GitHub](todo) and [Pijul Nest](todo) for

inspiration, since we would like to imitate the features that they supply, and we ultimately want use one or both of

these for our backends.

## User Flow

For the user flow we imagined what it would be like if the user was using a [REPL](todo) to interact with `radicle-surf`.

The general concept was that the user would enter the repository, build a view of the directory structure, and then

interact with the directories and files from there (called `browse`).

```haskell

repl :: IO ()

repl = do

  repo <- getRepo

  history <- getHistory label repo -- head is SHA1, tail is rest

  directory <- buildDirectory history

  forever browse directory

```

But then we thought about what happens when we are in `browse` but we would like to change the history and see that

file or directory at a different snapshot. This was captured in the pseudo-code below:

```haskell

  src_foo_bar <- find...

  history' <- historyOf src_foo_bar

```

This information was enough for us to begin the [denotational design](#denotational-design) below.

## Denotational Design

```haskell

-- A Label is a name for a directory or a file

type Label

μ Label = Text

-- A Directory captures its own Label followed by 1 or more

-- artefacts which can either be sub-directories or files.

--

-- An example of "foo/bar.hs" structure:

--  foo

--  |-- bar.hs

--

-- Would look like:

-- @("foo", Right ("bar.hs", "module Banana ...") :| [])@

type Directory

μ Directory = (Label, NonEmpty (Either Directory File))

-- DirectoryContents can either be the special IsRepo object,

-- a Directory, or a File.

type DirectoryContents

μ DirectoryContents = IsRepo | Directory | File

-- Opaque representation of repository state directories (e.g. `.git`, `.pijul`)

-- Those are not browseable, but have to be present at the repo root 'Directory'.

type IsRepo

-- A Directory captures its own Label followed by 1 or more DirectoryContents

--

-- An example of "foo/bar.hs" structure:

--  foo

--  |-- bar.hs

--

-- Would look like:

-- @("~", IsRepo :| [Directory ("foo", File ("bar.hs", "module Banana ..") :| [])]

-- where IsRepo is the implicit root of the repository.

type Directory

μ Directory = (Label, NonEmpty DirectoryContents)

-- A File is its Label and its contents

type File

μ File = (Label, ByteString)

-- An enumeration of what file-system artefact we're looking at.

-- Useful for listing a directory and denoting what the label is

-- corresponding to.

type SystemType

μ SystemType

  = IsFile

  | IsDirectory

-- A Chnage is an enumeration of how a file has changed.

-- This is simply used for getting the difference between two

-- directories.

type Change

-- Constructors of Change - think GADT

AddLineToFile :: NonEmpty Label -> Location -> ByteString -> Change

RemoveLineFromFile :: NonEmpty Label -> Location -> Change

MoveFile :: NonEmpty Label -> NonEmpty Label -> Change

CreateFile :: NonEmpty Label -> Change

DeleteFile :: NonEmpty Label -> Change

-- A Diff is a set of Changes that were made

type Diff

μ Diff = [Change]

-- History is an ordered set of @a@s. The reason for it being

-- polymorphic is that it allows us to choose what set artefact we

-- want to carry around.

--

-- For example:

--  * In `git` this would be a `Commit`.

--  * In `pijul` it would be a `Patch`.

type History a

μ History = NonEmpty a

-- A Repo is a collection of multiple histories.

-- This would essentially boil down to branches and tags.

type Repo

μ Repo a = [History a]

-- A Snapshot is a way of converting a History into a Directory.

-- In other words it gives us a snapshot of the history in the form of a directory.

type Snapshot a

μ Snapshot a = History a -> Directory

-- For example, we have a `git` snapshot or a `pjul` snapshot.

type Commit

type GitSnapshot   = Snapshot Commit

type Patch

type PijulSnapshot = Snapshot Patch

-- This is piece de resistance of the design! It turns out,

-- everything is just a Monad after all.

--

-- Our code Browser is a stateful computation of what History

-- we are currently working with and how to get a Snapshot of it.

type Browser a b

μ type Browser a b = ReaderT (Snapshot a) (State (History a) b)

-- A function that will retrieve a repository given an

-- identifier. In our case the identifier is opaque to the system.

getRepo :: Repo -> Repo

-- Find a particular History in the Repo. Again, how these things

-- are equated and found is opaque, but we can think of them as

-- branch or tag labels.

getHistory :: Eq a => History a -> Repo a -> Maybe (History a)

μ getHistory history repo =

  find history (μ repo)

-- Find if a particular artefact occurs in 0 or more histories.

findInHistories :: a -> [History a] -> [History a]

μ findInHistories a histories =

  filterMaybe (findInHistory a) histories

-- Find a particular artefact is in a history.

findInHistory :: Eq a => a -> History a -> Maybe a

μ findInHistory a history = find (== a) (μ history)

-- A special Label that guarantees a starting point, i.e. ~

rootLabel :: Label

μ rootLabel = "~"

emptyRepoRoot :: Directory

μ emptyRepoRoot = (rootLabel, IsRepo :| [])

-- Get the difference between two directory views.

diff :: Directory -> Directory -> Diff

-- List the current file or directories in a given Directory view.

listDirectory :: Directory -> [Label, SystemType]

μ listDirectory directory = foldMap toLabel $ snd (μ directory)

  where

    toLabel content = case content of

      File      (label, _) -> [(label, IsFile)]

      Directory (label, _) -> [(label, IsDirectory)]

      IsRepo               -> []

fileName :: File -> Label

μ fileName file = fst (μ file)

findFile :: NonEmpty Label -> Directory -> Maybe File

μ findFile (label :| labels) (Directory (label', contents)) =

  if label == label' then go labels contents else Nothing

  where

    findFileWithLabel :: Foldable f => Label -> f DirectoryContents -> Maybe File

    findFileWithLabel label = find (\artefact -> case content of

      File (fileLabel, _) -> fileLabel == label

      Directory _         -> False

      IsRepo              -> False)

    go :: [Label] -> NonEmpty DirectoryContents -> Just File

    go []             _        = Nothing

    go [label]        contents = findMaybe (fileWithLabel label) contents

    go (label:labels) contents = (go labels . snd) <$> find ((label ==) . fst) onlyDirectories contents

onlyDirectories :: Foldable f => f DirectoryContents -> [Directory]

μ onlyDirectories = fmapMaybe (\content -> case content of

  d@(Directory _) -> Just d

  File _          -> Nothing

  IsRepo          -> Nothing) . toList

getSubDirectories :: Directory -> [Directory]

μ getSubDirectories directory = foldMap f $ snd (μ directory)

  where

    f :: DirectoryContents -> [Directory]

    f = \case

      d@(Directory _) -> [d]

      File _          -> []

      IsRepo          -> []

-- Definition elided

findDirectory :: NonEmpty Label -> Directory -> Maybe Directory

-- Definition elided

fuzzyFind :: Label -> [Directory]

-- A Git Snapshot is grabbing the HEAD commit of your History

-- and turning it into a Directory

gitSnapshot :: Snapshot Commit

μ gitSnapshot commits = second (\root -> root <> getDirectoryPtr $ Nel.head commits) emptyRepoRoot

-- Opaque and defined by the backend

getDirectoryPtr :: Commit -> Directory

-- A Pijul history is semantically applying the patches in a

-- topological order and achieving the Directory view.

pijulHistory :: Snapshot Patch

μ pijulHistory = foldl pijulMagic emptyRepoRoot

-- Opaque and defined by the backend

pijulMagic :: Patch -> Directory -> Directory

-- Get the current History we are working with.

getHistory :: Browser a (History a)

μ getHistory = get

setHistory :: History a -> Browser a ()

μ setHistory = put

-- Get the current Directory in the Browser

getDirectory :: Browser a Directory

μ getDirectory = do

  hist <- get

  applySnapshot <- ask

  pure $ applySnapshot hist

-- We modify the history by changing the internal history state.

switchHistory :: (History a -> History a) -> Browser a b

μ switchHistory f = modify f

-- | Find the suffix of a History.

findSuffix :: Eq a => a -> History a -> Maybe (History a)

μ findSuffix a = nonEmpty . Nel.dropWhile (/= a)

-- View the history up to a given point by supplying a function to modify

-- the state. If this operation fails, then the default value is used.

viewAt :: (History a -> Maybe (History a)) -> History a -> Browser a b

μ viewAt f def = switchHistory (fromMaybe def . f)

```

# An updated design for radicle-surf

This is a design blueprint for the new `radicle-git/radicle-surf` crate. The

actual design details and implemenation are described and updated in its

documentation comments, viewable via `cargo doc`.

## Introduction

In September 2022, we have ported the [`radicle-surf` crate](https://github.com/radicle-dev/radicle-surf)

from its own github repo to be part of the [`radicle-git` repo](https://github.com/radicle-dev/radicle-git).

We are taking this opportunity to refactor its design as well. Intuitively,

`radicle-surf` provides an API so that one can use it to create a GitHub-like

UI for a git repo:

1. Code browsing: given a specific commit/ref, browse files and directories.

2. Diff between two revisions that resolve into two commits.

3. Retrieve the history of commits with a given head, and optionally a file.

4. List refs and retrieve their metadata: Branches, Tags, Remotes,

Notes and user-defined "categories", where a category is: `refs/<category>/<...>`.

## Motivation

The `radicle-surf` crate aims to provide a safe and easy-to-use API that

supports the features listed in [Introduction](#introduction). Based on the

existing API, the main goals of the refactoring are:

- API review: identify the issues with the current API.

- Updated API: propose an updated API that reuses parts of the existing API.

- Address open issues in the original `radicle-surf` repo.

- Be `git` specific. (i.e. no need to support other VCS systems)

- Remove `git2` from the public API. The use of `git2` should be an

implementation detail.

## API review

In this section, we review some core types in the current API and propose

changes to them. The main theme is to make the API simpler and easier to use.

### Remove the `Browser` type

The type [`Browser`](https://github.com/radicle-dev/radicle-surf/blob/b85d2183d786e5fa447aab9d2f420a32f1061bfa/surf/src/vcs.rs#L145) is awkward:

- it is not a source of truth of any information. For example, `list_branches`

method is just a wrapper of `Repository::list_branches`.

- it takes in `History`, but really operates at the `Snapshot` level.

- it is mutable but its state mutations are not used much.

Can we just remove `Browser` and implement its functionalities using other

types?

- For iteratoring the history, use `History`.

- For generating `Directory`, use `Repository` directly given a `Rev`.

- For accessing `Branch`, `Tag` or `Commit`, use `Repository`.

### Remove the `Snapshot` type

A [`Snapshot`](https://github.com/radicle-dev/radicle-surf/blob/b85d2183d786e5fa447aab9d2f420a32f1061bfa/surf/src/vcs.rs#L140) should be really

just a tree (or `Directory`) of a `Commit` in git. Currently it is a function

that returns a `Directory`. As we are moving to be git specific, we don't need

to have this generic function to create a snapshot across different VCS systems.

The snapshot function can be easily implement as a method of `RepositoryRef`.

### Simplify `Directory` and remove the `Tree` and `Forest` types

The [`Directory`](https://github.com/radicle-dev/radicle-surf/blob/b85d2183d786e5fa447aab9d2f420a32f1061bfa/surf/src/file_system/directory.rs#L144)

type represents the file system view of a snapshot. Its field

`sub_directories` is defined a `Forest` based on `Tree`. The types are

over-engineered from such a simple concept. We could refactor `Directory` to

use `DirectoryContents` for its items and not to use `Tree` or `Forest` at all.

We also found the `list_directory()` method duplicates with `iter()` method.

Hence `list_directory()` is removed, together with `SystemType` type.

### Remove `Vcs` trait

The `Vcs` trait was introduced to support different version control backends,

for example both Git and Pijul, and potentially others. However, since this

port is part of `radicle-git` repo, we are only supporting Git going forward.

We no longer need another layer of indirection defined by `Vcs` trait.

## The new API

With the changes proposed in the previous section, we describe what the new API

would look like and how they meet the requirements.

### Basic types

#### Repository

`Repository` is kept as the entry point of the API, even though its methods

would change due to changes in other types. Also, we would like to consolidate

[`Repository`](https://github.com/radicle-dev/radicle-surf/blob/b85d2183d786e5fa447aab9d2f420a32f1061bfa/surf/src/vcs/git/repo.rs#L53) and

 [`RepositoryRef`](https://github.com/radicle-dev/radicle-surf/blob/b85d2183d786e5fa447aab9d2f420a32f1061bfa/surf/src/vcs/git/repo.rs#L63) to

 simplify the API.

#### Revision and Commit

In Git, `Revision` commonly resolves into a `Commit` but could refer to other

objects for example a `Blob`. Hence we need to keep both concepts in the API.

Currently we have multiple types to identify a `Commit` or `Revision`.

- Commit

- Oid

- Rev

The relations between them are: all `Rev` and `Commit` can resolve into `Oid`,

and in most cases `Rev` can resolve into `Commit`.

On one hand, `Oid` is the ultimate unique identifer but it is more machine-

friendly than human-friendly. On the other hand, `Revision` is most human-

friendly and better suited in the API interface. A conversion from `Revision`

to `Oid` will be useful.

For the places where `Commit` is required, we should explicitly ask for

`Commit` instead of `Revision`.

In conclusion, we define two new traits to support the use of `Revision` and

`Commit`:

```Rust

pub trait Revision {

    /// Resolves a revision into an object id in `repo`.

    fn object_id(&self, repo: &RepositoryRef) -> Result<Oid, Error>;

}

pub trait ToCommit {

    /// Converts to a commit in `repo`.

    fn to_commit(self, repo: &RepositoryRef) -> Result<Commit, Error>;

}

```

These two traits will be implemented for most common representations of

`Revision` and `Commit`, for example `&str`, refs like `Branch`, `Tag`, etc.

Our API will use these traits where we expect a `Revision` or a `Commit`.

#### History

The current `History` is generic over VCS types and also retrieves the full list

of commits when the history is created. The VCS part can be removed and the

history can lazy-load the list of commits by implmenting `Iterator` to support

 potentially very long histories.

We can also store the head commit with the history so that it's easy to get

the start point and it helps to identify the history.

To support getting the history of a file, we provide methods to modify a

`History` to filter by a file path.

The new `History` type would look like this:

```Rust

pub struct History<'a> {

    repo: RepositoryRef<'a>,

    head: Commit,

    revwalk: git2::Revwalk<'a>,

    filter_by: Option<FilterBy>,

}

enum FilterBy {

    File { path: file_system::Path },

}

```

For the methods provided by `History`, please see section [Retrieve the history](#retrieve-the-history) below.

#### Commit

`Commit` is a central concept in Git. In `radicle-surf` we define `Commit` type

to represent its metadata:

```Rust

pub struct Commit {

    /// Object Id

    pub id: Oid,

    /// The author of the commit.

    pub author: Author,

    /// The actor who committed this commit.

    pub committer: Author,

    /// The long form message of the commit.

    pub message: String,

    /// The summary message of the commit.

    pub summary: String,

    /// The parents of this commit.

    pub parents: Vec<Oid>,

}

```

To get the file system snapshot of the commit, the user should use

`root_dir` method described in [Code browsing](#code-browsing) section.

To get the diff of the commit, the user should use `diff_commit` method

described in [Diffs](#diffs) section. Note that we might move that method to

`Commit` type itself.

### Code browsing

The user should be able to browse the files and directories for any given

commit. The core API is:

- Create a root Directory:

```Rust

impl RepositoryRef {

    pub fn root_dir<C: ToCommit>(&self, commit: C) -> Result<Directory, Error>;

}

```

- Browse a Directory's contents:

```Rust

impl Directory {

    pub fn contents(&self) -> impl Iterator<Item = &DirectoryContents>;

}

```

where `DirectoryContents` supports both files and sub-directories:

```Rust

pub enum DirectoryContents {

    /// The `File` variant contains the file's name and the [`File`] itself.

    File {

        /// The name of the file.

        name: Label,

        /// The file data.

        file: File,

    },

    /// The `Directory` variant contains a sub-directory to the current one.

    Directory(Directory),

}

```

### Diffs

The user would be able to create a diff between any two revisions. In the first

implementation, these revisions have to resolve into commits. But in future,

the revisions could refer to other objects, e.g. files (blobs).

The core API is:

```Rust

impl RepositoryRef {

    /// Returns the diff between two revisions.

    pub fn diff<R: Revision>(&self, from: R, to: R) -> Result<Diff, Error>;

}

```

To obtain the diff of a particular commit, we will have:

```Rust

impl RepositoryRef {

    pub fn diff_commit(&self, commit: impl ToCommit) -> Result<Diff, Error>;

}

```

### Retrieve the history

The user would be able to get the list of previous commits reachable from a

particular commit.

To create a `History` from a repo with a given head:

```Rust

impl RepositoryRef {

    pub fn history<C: ToCommit>(&self, head: C) -> Result<History, Error>;

}

```

To access the `History`, the user simply iterates `History` as it implements the

`Iterator` trait that produces `Result<Commit, Error>`.

`History` provides a method to filter based on a path and other helper methods:

```Rust

impl<'a> History<'a> {

    /// Returns the head commit of a history.

    pub fn head(&self) -> &Commit;

    // Modifies a history with a filter by `path`.

    // This is to support getting the history of a file.

    pub fn by_path(mut self, path: file_system::Path) -> Self;

```

- Alternative design:

One potential downside of define `History` as an iterator is that:

`history.next()` takes a mutable history object. A different design is to use

`History` as immutable object that produces an iterator on-demand:

```Rust

pub struct History<'a> {

    repo: RepositoryRef<'a>,

    head: Commit,

}

impl<'a> History<'a> {

    /// This method creats a new `RevWalk` internally and return an

    /// iterator for all commits in a history.

    pub fn iter(&self) -> impl Iterator<Item = Commit>;

}

```

In this design, `History` does not keep `RevWalk` in its state. It will create

a new one when `iter()` is called. I like the immutable interface of this design

but did not implement it in the current code mainly because the libgit2 doc says

[creating a new `RevWalk` is relatively expensive](https://libgit2.org/libgit2/#HEAD/group/revwalk/git_revwalk_new).

### List refs and retrieve their metadata

Git refs are simple names that point to objects using object IDs. In this new

design, we no longer group different refs into a single enum. Instead, each kind

of ref would be their own type, e.g. `Tag`, `Branch`, `Namespace`, etc.

To retrieve the refs, the user would call the `<ref_type>s()` method of a

repo, e.g. `branches()`, `tags()`. The result is an iterator of available refs,

e.g. `Branches`.

```Rust

impl RepositoryRef {

    /// Lists branch names with `filter`.

    pub fn branches<G>(&self, pattern: G) -> Result<Branches, Error>

    where

        G: Into<Glob<Branch>>

}

```

### Git Tree and Blob

In Git, a `Blob` object represents the content of a file, and a `Tree` object

represents the content of a listing (in a directory). A `Tree` or a `Blob` does

not have its own name because there could be different names (paths) pointing

to the same `Tree` or `Blob`. In contrast, a `Directory` or a `File` has names

included and possible other attributes.

In `radicle-surf` API, we would expose `Tree` and `Blob` as defined in Git, i.e.

as the content only, with some extra helper methods, for example `commit()` that

returns the commit that created the object.

The `Repository` provides methods to retrieve `Tree` or `Blob` for a given path.

## Summary

This design document was created as a guideline for refactoring the

`radicle-surf` crate when we move it into the `radicle-git` repo. As the code

evolves, this document would not be matching the actual code exactly. However

we can still come back to this document to learn about the history of the

design and update it when needed.

//! An example of browsing a git repo using `radicle-surf`.

//!

//! How to run:

//!

//!     cargo run --example browsing <git_repo_path>

//!

//! This program browses the given repo and prints out the files and

//! the directories in a tree-like structure.

use radicle_surf::{

    fs::{self, Directory},

    Repository,

};

use std::{env, time::Instant};

fn main() {

    let repo_path = match env::args().nth(1) {

        Some(path) => path,

        None => {

            print_usage();

            return;

        }

    };

    let repo = Repository::discover(repo_path).unwrap();

    let now = Instant::now();

    let head = repo.head().unwrap();

    let root = repo.root_dir(head).unwrap();

    print_directory(&root, &repo, 0);

    let elapsed_millis = now.elapsed().as_millis();

    println!("browse with print: {elapsed_millis} ms");

}

fn print_directory(d: &Directory, repo: &Repository, indent_level: usize) {

    let indent = " ".repeat(indent_level * 4);

    println!("{}{}/", &indent, d.name());

    for entry in d.entries(repo).unwrap() {

        match entry {

            fs::Entry::File(f) => println!("    {}{}", &indent, f.name()),

            fs::Entry::Directory(d) => print_directory(&d, repo, indent_level + 1),

            fs::Entry::Submodule(s) => println!("    {}{}", &indent, s.name()),

        }

    }

}

fn print_usage() {

    println!("Usage:");

    println!("cargo run --example browsing <repo_path>");

}

extern crate radicle_surf;

use std::{env::Args, str::FromStr, time::Instant};

use radicle_git_ext::Oid;

use radicle_surf::{diff::Diff, Repository};

fn main() {

    let options = get_options_or_exit();

    let repo = init_repository_or_exit(&options.path_to_repo);

    let head_oid = match options.head_revision {

        HeadRevision::Head => repo.head().unwrap(),

        HeadRevision::Commit(id) => Oid::from_str(&id).unwrap(),

    };

    let base_oid = Oid::from_str(&options.base_revision).unwrap();

    let now = Instant::now();

    let elapsed_nanos = now.elapsed().as_nanos();

    let diff = repo.diff(base_oid, head_oid).unwrap();

    print_diff_summary(&diff, elapsed_nanos);

}

fn get_options_or_exit() -> Options {

    match Options::parse(std::env::args()) {

        Ok(options) => options,

        Err(message) => {

            println!("{message}");

            std::process::exit(1);

        }

    }

}

fn init_repository_or_exit(path_to_repo: &str) -> Repository {

    match Repository::open(path_to_repo) {

        Ok(repo) => repo,

        Err(e) => {

            println!("Failed to create repository: {e:?}");

            std::process::exit(1);

        }

    }

}

fn print_diff_summary(diff: &Diff, elapsed_nanos: u128) {

    diff.added().for_each(|created| {

        println!("+++ {:?}", created.path);

    });

    diff.deleted().for_each(|deleted| {

        println!("--- {:?}", deleted.path);

    });

    diff.modified().for_each(|modified| {

        println!("mod {:?}", modified.path);

    });

    println!(

        "created {} / deleted {} / modified {} / total {}",

        diff.added().count(),

        diff.deleted().count(),

        diff.modified().count(),

        diff.added().count() + diff.deleted().count() + diff.modified().count()

    );

    println!("diff took {elapsed_nanos} nanos ");

}

struct Options {

    path_to_repo: String,

    base_revision: String,

    head_revision: HeadRevision,

}

enum HeadRevision {

    Head,

    Commit(String),

}

impl Options {

    fn parse(args: Args) -> Result<Self, String> {

        let args: Vec<String> = args.collect();

        if args.len() != 4 {

            return Err(format!(

                "Usage: {} <path-to-repo> <base-revision> <head-revision>\n\

                \tpath-to-repo: Path to the directory containing .git subdirectory\n\

                \tbase-revision: Git commit ID of the base revision (one that will be considered less recent)\n\

                \thead-revision: Git commit ID of the head revision (one that will be considered more recent) or 'HEAD' to use current git HEAD\n",

                args[0]));

        }

        let path_to_repo = args[1].clone();

        let base_revision = args[2].clone();

        let head_revision = {

            if args[3].eq_ignore_ascii_case("HEAD") {

                HeadRevision::Head

            } else {

                HeadRevision::Commit(args[3].clone())

            }

        };

        Ok(Options {

            path_to_repo,

            base_revision,

            head_revision,

        })

    }

}

#!/usr/bin/env bash

set -euo pipefail

# Verify that the script is run from project root.

BASE=$(basename "$(pwd)")

if [ "${BASE}" != "radicle-surf" ]

then

   echo "ERROR: this script should be run from the root of radicle-surf"

   exit 1

fi

TARBALL_PATH=data/git-platinum.tgz

WORKDIR=.workdir

PLATINUM_REPO="$WORKDIR/git-platinum"

# Create the workdir if needed.

mkdir -p $WORKDIR

# This is here in case the last script run failed and it never cleaned up.

rm -rf "$PLATINUM_REPO"

# Clone an up-to-date version of git-platinum.

git clone https://github.com/radicle-dev/git-platinum.git "$PLATINUM_REPO"

git -C "$PLATINUM_REPO" checkout empty-branch

git -C "$PLATINUM_REPO" checkout diff-test

git -C "$PLATINUM_REPO" checkout dev

# Add the necessary refs.

input="./data/mock-branches.txt"

while IFS= read -r line

do

    IFS=, read -ra pair <<< "$line"

    echo "Creating branch ${pair[0]}"

    git -C "$PLATINUM_REPO" update-ref "${pair[0]}" "${pair[1]}"

done < "$input"

# Update the archive.

tar -czf $WORKDIR/git-platinum.tgz -C $WORKDIR git-platinum

mv $WORKDIR/git-platinum.tgz $TARBALL_PATH

# Clean up.

rm -rf "$PLATINUM_REPO"

//! Represents git object type 'blob', i.e. actual file contents.

//! See git [doc](https://git-scm.com/book/en/v2/Git-Internals-Git-Objects) for more details.

use std::ops::Deref;

use radicle_git_ext::Oid;

#[cfg(feature = "serde")]

use serde::{

    ser::{SerializeStruct as _, Serializer},

    Serialize,

};

use crate::Commit;

/// Represents a git blob object.

///

/// The type parameter `T` can be fulfilled by [`BlobRef`] or a

/// [`Vec`] of bytes.

pub struct Blob<T> {

    id: Oid,

    is_binary: bool,

    commit: Commit,

    content: T,

}

impl<T> Blob<T> {

    pub fn object_id(&self) -> Oid {

        self.id

    }

    pub fn is_binary(&self) -> bool {

        self.is_binary

    }

    /// Returns the commit that created this blob.

    pub fn commit(&self) -> &Commit {

        &self.commit

    }

    pub fn content(&self) -> &[u8]

    where

        T: AsRef<[u8]>,

    {

        self.content.as_ref()

    }

    pub fn size(&self) -> usize

    where

        T: AsRef<[u8]>,

    {

        self.content.as_ref().len()

    }

}

impl<'a> Blob<BlobRef<'a>> {

    /// Returns the [`Blob`] wrapping around an underlying [`git2::Blob`].

    pub(crate) fn new(id: Oid, git2_blob: git2::Blob<'a>, commit: Commit) -> Self {

        let is_binary = git2_blob.is_binary();

        let content = BlobRef { inner: git2_blob };

        Self {

            id,

            is_binary,

            content,

            commit,

        }

    }

    /// Converts into a `Blob` with owned content bytes.

    pub fn to_owned(&self) -> Blob<Vec<u8>> {

        Blob {

            id: self.id,

            content: self.content.to_vec(),

            commit: self.commit.clone(),

            is_binary: self.is_binary,

        }

    }

}

/// Represents a blob with borrowed content bytes.

pub struct BlobRef<'a> {

    pub(crate) inner: git2::Blob<'a>,

}

impl BlobRef<'_> {

    pub fn id(&self) -> Oid {

        self.inner.id().into()

    }

}

impl AsRef<[u8]> for BlobRef<'_> {

    fn as_ref(&self) -> &[u8] {

        self.inner.content()

    }

}

impl Deref for BlobRef<'_> {

    type Target = [u8];

    fn deref(&self) -> &Self::Target {

        self.inner.content()

    }

}

#[cfg(feature = "serde")]

impl<T> Serialize for Blob<T>

where

    T: AsRef<[u8]>,

{

    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

    where

        S: Serializer,

    {

        use base64::Engine as _;

        const FIELDS: usize = 4;

        let mut state = serializer.serialize_struct("Blob", FIELDS)?;

        state.serialize_field("id", &self.id)?;

        state.serialize_field("binary", &self.is_binary())?;

        let bytes = self.content.as_ref();

        match std::str::from_utf8(bytes) {

            Ok(s) => state.serialize_field("content", s)?,

            Err(_) => {

                let encoded = base64::prelude::BASE64_STANDARD.encode(bytes);

                state.serialize_field("content", &encoded)?

            }

        };

        state.serialize_field("lastCommit", &self.commit)?;

        state.end()

    }

}

#[cfg(feature = "serde")]

impl Serialize for BlobRef<'_> {

    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

    where

        S: Serializer,

    {

        use base64::Engine as _;

        const FIELDS: usize = 3;

        let mut state = serializer.serialize_struct("BlobRef", FIELDS)?;

        state.serialize_field("id", &self.id())?;

        state.serialize_field("binary", &self.inner.is_binary())?;

        let bytes = self.as_ref();

        match std::str::from_utf8(bytes) {

            Ok(s) => state.serialize_field("content", s)?,

            Err(_) => {

                let encoded = base64::prelude::BASE64_STANDARD.encode(bytes);

                state.serialize_field("content", &encoded)?

            }

        };

        state.end()

    }

}

use std::{

    convert::TryFrom,

    str::{self, FromStr},

};

use git_ext::ref_format::{component, lit, Component, Qualified, RefStr, RefString};

use crate::refs::refstr_join;

/// A `Branch` represents any git branch. It can be [`Local`] or [`Remote`].

///

/// Note that if a `Branch` is created from a [`git2::Reference`] then

/// any `refs/namespaces` will be stripped.

#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]

#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]

pub enum Branch {

    Local(Local),

    Remote(Remote),

}

impl Branch {

    /// Construct a [`Local`] branch.

    pub fn local<R>(name: R) -> Self

    where

        R: AsRef<RefStr>,

    {

        Self::Local(Local::new(name))

    }

    /// Construct a [`Remote`] branch.

    /// The `remote` is the remote name of the reference name while

    /// the `name` is the suffix, i.e. `refs/remotes/<remote>/<name>`.

    pub fn remote<R>(remote: Component<'_>, name: R) -> Self

    where

        R: AsRef<RefStr>,

    {

        Self::Remote(Remote::new(remote, name))

    }

    /// Return the short `Branch` refname,

    /// e.g. `fix/ref-format`.

    pub fn short_name(&self) -> &RefString {

        match self {

            Branch::Local(local) => local.short_name(),

            Branch::Remote(remote) => remote.short_name(),

        }

    }

    /// Give back the fully qualified `Branch` refname,

    /// e.g. `refs/remotes/origin/fix/ref-format`,

    /// `refs/heads/fix/ref-format`.

    pub fn refname<'a>(&'a self) -> Qualified<'a> {

        match self {

            Branch::Local(local) => local.refname(),

            Branch::Remote(remote) => remote.refname(),

        }

    }

}

impl TryFrom<&git2::Reference<'_>> for Branch {

    type Error = error::Branch;

    fn try_from(reference: &git2::Reference<'_>) -> Result<Self, Self::Error> {

        let name = str::from_utf8(reference.name_bytes())?;

        Self::from_str(name)

    }

}

impl TryFrom<&str> for Branch {

    type Error = error::Branch;

    fn try_from(name: &str) -> Result<Self, Self::Error> {

        Self::from_str(name)

    }

}

impl FromStr for Branch {

    type Err = error::Branch;

    fn from_str(name: &str) -> Result<Self, Self::Err> {

        let name = RefStr::try_from_str(name)?;

        let name = match name.to_namespaced() {

            None => name

                .qualified()

                .ok_or_else(|| error::Branch::NotQualified(name.to_string()))?,

            Some(name) => name.strip_namespace_recursive(),

        };

        let (_ref, category, c, cs) = name.non_empty_components();

        if category == component::HEADS {

            Ok(Self::Local(Local::new(refstr_join(c, cs))))

        } else if category == component::REMOTES {

            Ok(Self::Remote(Remote::new(c, cs.collect::<RefString>())))

        } else {

            Err(error::Branch::InvalidName(name.into()))

        }

    }

}

/// A `Local` represents a local branch, i.e. it is a reference under

/// `refs/heads`.

///

/// Note that if a `Local` is created from a [`git2::Reference`] then

/// any `refs/namespaces` will be stripped.

#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]

#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]

pub struct Local {

    name: RefString,

}

impl Local {

    /// Construct a new `Local` with the given `name`.

    ///

    /// If the name is qualified with `refs/heads`, this will be

    /// shortened to the suffix. To get the `Qualified` name again,

    /// use [`Local::refname`].

    pub(crate) fn new<R>(name: R) -> Self

    where

        R: AsRef<RefStr>,

    {

        match name.as_ref().qualified() {

            None => Self {

                name: name.as_ref().to_ref_string(),

            },

            Some(qualified) => {

                let (_refs, heads, c, cs) = qualified.non_empty_components();

                if heads == component::HEADS {

                    Self {

                        name: refstr_join(c, cs),

                    }

                } else {

                    Self {

                        name: name.as_ref().to_ref_string(),

                    }

                }

            }

        }

    }

    /// Return the short `Local` refname,

    /// e.g. `fix/ref-format`.

    pub fn short_name(&self) -> &RefString {

        &self.name

    }

    /// Return the fully qualified `Local` refname,

    /// e.g. `refs/heads/fix/ref-format`.

    pub fn refname<'a>(&'a self) -> Qualified<'a> {

        lit::refs_heads(&self.name).into()

    }

}

impl TryFrom<&git2::Reference<'_>> for Local {

    type Error = error::Local;

    fn try_from(reference: &git2::Reference) -> Result<Self, Self::Error> {

        let name = str::from_utf8(reference.name_bytes())?;

        Self::from_str(name)

    }

}

impl TryFrom<&str> for Local {

    type Error = error::Local;

    fn try_from(name: &str) -> Result<Self, Self::Error> {

        Self::from_str(name)

    }

}

impl FromStr for Local {

    type Err = error::Local;

    fn from_str(name: &str) -> Result<Self, Self::Err> {

        let name = RefStr::try_from_str(name)?;

        let name = match name.to_namespaced() {

            None => name

                .qualified()

                .ok_or_else(|| error::Local::NotQualified(name.to_string()))?,

            Some(name) => name.strip_namespace_recursive(),

        };

        let (_ref, heads, c, cs) = name.non_empty_components();

        if heads == component::HEADS {

            Ok(Self::new(refstr_join(c, cs)))

        } else {

            Err(error::Local::NotHeads(name.into()))

        }

    }

}

/// A `Remote` represents a remote branch, i.e. it is a reference under

/// `refs/remotes`.

///

/// Note that if a `Remote` is created from a [`git2::Reference`] then

/// any `refs/namespaces` will be stripped.

#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]

#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]

pub struct Remote {

    remote: RefString,

    name: RefString,

}

impl Remote {

    /// Construct a new `Remote` with the given `name` and `remote`.

    ///

    /// ## Note

    /// `name` is expected to be in short form, i.e. not begin with

    /// `refs`.

    ///

    /// If you are creating a `Remote` with a name that begins with

    /// `refs/remotes`, use [`Remote::from_refs_remotes`] instead.

    ///

    /// To get the `Qualified` name, use [`Remote::refname`].

    pub(crate) fn new<R>(remote: Component, name: R) -> Self

    where

        R: AsRef<RefStr>,

    {

        Self {

            name: name.as_ref().to_ref_string(),

            remote: remote.to_ref_string(),

        }

    }

    /// Parse the `name` from the form `refs/remotes/<remote>/<rest>`.

    ///

    /// If the `name` is not of this form, then `None` is returned.

    pub fn from_refs_remotes<R>(name: R) -> Option<Self>

    where

        R: AsRef<RefStr>,

    {

        let qualified = name.as_ref().qualified()?;

        let (_refs, remotes, remote, cs) = qualified.non_empty_components();

        (remotes == component::REMOTES).then_some(Self {

            name: cs.collect(),

            remote: remote.to_ref_string(),

        })

    }

    /// Return the short `Remote` refname,

    /// e.g. `fix/ref-format`.

    pub fn short_name(&self) -> &RefString {

        &self.name

    }

    /// Return the remote of the `Remote`'s refname,

    /// e.g. `origin`.

    pub fn remote(&self) -> &RefString {

        &self.remote

    }

    /// Give back the fully qualified `Remote` refname,

    /// e.g. `refs/remotes/origin/fix/ref-format`.

    pub fn refname<'a>(&'a self) -> Qualified<'a> {

        lit::refs_remotes(self.remote.join(&self.name)).into()

    }

}

impl TryFrom<&git2::Reference<'_>> for Remote {

    type Error = error::Remote;

    fn try_from(reference: &git2::Reference) -> Result<Self, Self::Error> {

        let name = str::from_utf8(reference.name_bytes())?;

        Self::from_str(name)

    }

}

impl TryFrom<&str> for Remote {

    type Error = error::Remote;

    fn try_from(name: &str) -> Result<Self, Self::Error> {

        Self::from_str(name)

    }

}

impl FromStr for Remote {

    type Err = error::Remote;

    fn from_str(name: &str) -> Result<Self, Self::Err> {

        let name = RefStr::try_from_str(name)?;

        let name = match name.to_namespaced() {

            None => name

                .qualified()

                .ok_or_else(|| error::Remote::NotQualified(name.to_string()))?,

            Some(name) => name.strip_namespace_recursive(),

        };

        let (_ref, remotes, remote, cs) = name.non_empty_components();

        if remotes == component::REMOTES {

            Ok(Self::new(remote, cs.collect::<RefString>()))

        } else {

            Err(error::Remote::NotRemotes(name.into()))

        }

    }

}

pub mod error {

    use radicle_git_ext::ref_format::{self, RefString};

    use thiserror::Error;

    #[derive(Debug, Error)]

    pub enum Branch {

        #[error("the refname '{0}' did not begin with 'refs/heads' or 'refs/remotes'")]

        InvalidName(RefString),

        #[error("the refname '{0}' did not begin with 'refs/heads' or 'refs/remotes'")]

        NotQualified(String),

        #[error(transparent)]

        RefFormat(#[from] ref_format::Error),

        #[error(transparent)]

        Utf8(#[from] std::str::Utf8Error),

    }

    #[derive(Debug, Error)]

    pub enum Local {

        #[error("the refname '{0}' did not begin with 'refs/heads'")]

        NotHeads(RefString),

        #[error("the refname '{0}' did not begin with 'refs/heads'")]

        NotQualified(String),

        #[error(transparent)]

        RefFormat(#[from] ref_format::Error),

        #[error(transparent)]

        Utf8(#[from] std::str::Utf8Error),

    }

    #[derive(Debug, Error)]

    pub enum Remote {

        #[error("the refname '{0}' did not begin with 'refs/remotes'")]

        NotQualified(String),

        #[error("the refname '{0}' did not begin with 'refs/remotes'")]

        NotRemotes(RefString),

        #[error(transparent)]

        RefFormat(#[from] ref_format::Error),

        #[error(transparent)]

        Utf8(#[from] std::str::Utf8Error),

    }

}

use std::{convert::TryFrom, str};

use radicle_git_ext::Oid;

use thiserror::Error;

#[cfg(feature = "serde")]

use serde::{ser::SerializeStruct, Deserialize, Deserializer, Serialize, Serializer};

#[derive(Debug, Error)]

pub enum Error {

    /// When trying to get the summary for a [`git2::Commit`] some action

    /// failed.

    #[error("an error occurred trying to get a commit's summary")]

    MissingSummary,

    #[error(transparent)]

    Utf8Error(#[from] str::Utf8Error),

}

/// Represents the authorship of actions in a git repo.

#[cfg_attr(feature = "serde", derive(Deserialize, Serialize))]

#[derive(Clone, PartialEq, Eq, PartialOrd, Ord)]

pub struct Author {

    /// Name of the author.

    pub name: String,

    /// Email of the author.

    pub email: String,

    /// Time the action was taken, e.g. time of commit.