Struct radicle_surf::vcs::Browser

pub struct Browser<Repo, A, Error> { /* fields omitted */ }

A Browser is a way of rendering a History into a Directory snapshot, and the current History it is viewing.

Implementations

impl<'a> Browser<RepositoryRef<'a>, Commit, Error>

pub fn new(
    repository: impl Into<RepositoryRef<'a>>,
    rev: impl Into<Rev>
) -> Result<Self, Error>

Create a new browser to interact with.

The revspec provided will be used to kick off the History for this Browser.

Errors

• error::Error::Git

Examples

use radicle_surf::vcs::git::{Browser, Branch, Repository};

let repo = Repository::new("./data/git-platinum")?;
let browser = Browser::new(&repo, Branch::local("master"))?;

pub fn new_with_namespace(
    repository: impl Into<RepositoryRef<'a>>,
    namespace: &Namespace,
    rev: impl Into<Rev>
) -> Result<Self, Error>

Create a new Browser that starts in a given namespace.

Errors

• error::Error::Git

Examples

use radicle_surf::vcs::git::{Browser, Repository, Branch, RefScope, BranchName, Namespace};
use std::convert::TryFrom;

let repo = Repository::new("./data/git-platinum")?;
let browser = Browser::new_with_namespace(
    &repo,
    &Namespace::try_from("golden")?,
    Branch::local("master")
)?;

let mut branches = browser.list_branches(RefScope::Local)?;
branches.sort();

assert_eq!(
    branches,
    vec![
        Branch::local("banana"),
        Branch::local("master"),
    ]
);

pub fn switch_namespace(
    self,
    namespace: &Namespace,
    rev: impl Into<Ref>
) -> Result<Self, Error>

Switch the namespace you are browsing in. This will consume the previous Browser and give you back a new Browser for that particular namespace. The revision provided will kick-off the history for this Browser.

pub fn which_namespace(&self) -> Result<Option<Namespace>, Error>

What is the current namespace we’re browsing in.

pub fn head(&mut self) -> Result<(), Error>

Set the current Browser history to the HEAD commit of the underlying repository.

Errors

• error::Error::Git

Examples

use radicle_surf::vcs::git::{Browser, Repository, Branch};

let repo = Repository::new("./data/git-platinum")?;
let mut browser = Browser::new(&repo, Branch::local("master"))?;

// ensure we're at HEAD
browser.head();

let directory = browser.get_directory();

// We are able to render the directory
assert!(directory.is_ok());

pub fn branch(&mut self, branch: Branch) -> Result<(), Error>

Set the current Browser’s History to the given BranchName provided.

Errors

• error::Error::Git
• error::Error::NotBranch

Examples

use radicle_surf::vcs::git::{Branch, Browser, Repository};

let repo = Repository::new("./data/git-platinum")?;
let mut browser = Browser::new(&repo, Branch::local("master"))?;

// ensure we're on 'master'
browser.branch(Branch::local("master"));

let directory = browser.get_directory();

// We are able to render the directory
assert!(directory.is_ok());

use radicle_surf::vcs::git::{Branch, Browser, Repository};
use radicle_surf::file_system::{Label, Path, SystemType};
use radicle_surf::file_system::unsound;

let repo = Repository::new("./data/git-platinum")?;
let mut browser = Browser::new(&repo, Branch::local("master"))?;
browser.branch(Branch::remote("dev", "origin"))?;

let directory = browser.get_directory()?;
let mut directory_contents = directory.list_directory();
directory_contents.sort();

assert!(directory_contents.contains(
    &SystemType::file(unsound::label::new("here-we-are-on-a-dev-branch.lol"))
));

pub fn tag(&mut self, tag_name: TagName) -> Result<(), Error>

Set the current Browser’s History to the TagName provided.

Errors

• error::Error::Git
• error::Error::NotTag

Examples

use nonempty::NonEmpty;
use radicle_surf::vcs::History;
use radicle_surf::vcs::git::{TagName, Branch, Browser, Oid, Repository};

let repo = Repository::new("./data/git-platinum")?;
let mut browser = Browser::new(&repo, Branch::local("master"))?;

// Switch to "v0.3.0"
browser.tag(TagName::new("v0.3.0"))?;

let expected_history = History(NonEmpty::from((
    Oid::from_str("19bec071db6474af89c866a1bd0e4b1ff76e2b97")?,
    vec![
        Oid::from_str("f3a089488f4cfd1a240a9c01b3fcc4c34a4e97b2")?,
        Oid::from_str("2429f097664f9af0c5b7b389ab998b2199ffa977")?,
        Oid::from_str("d3464e33d75c75c99bfb90fa2e9d16efc0b7d0e3")?,
    ]
)));

let history_ids = browser.get().map(|commit| commit.id);

// We are able to render the directory
assert_eq!(history_ids, expected_history);

pub fn commit(&mut self, oid: Oid) -> Result<(), Error>

Set the current Browser’s History to the Oid (SHA digest) provided.

Errors

• error::Error::Git

Examples

use radicle_surf::file_system::{Label, SystemType};
use radicle_surf::file_system::unsound;
use radicle_surf::vcs::git::{Branch, Browser, Oid, Repository};
use std::str::FromStr;

let repo = Repository::new("./data/git-platinum")?;
let mut browser = Browser::new(&repo, Branch::local("master"))?;

// Set to the initial commit
let commit = Oid::from_str("e24124b7538658220b5aaf3b6ef53758f0a106dc")?;

browser.commit(commit)?;

let directory = browser.get_directory()?;
let mut directory_contents = directory.list_directory();

assert_eq!(
    directory_contents,
    vec![
        SystemType::file(unsound::label::new("README.md")),
        SystemType::directory(unsound::label::new("bin")),
        SystemType::directory(unsound::label::new("src")),
        SystemType::directory(unsound::label::new("this")),
    ]
);

pub fn rev(&mut self, rev: impl Into<Rev>) -> Result<(), Error>

Set a Browser’s History based on a revspec.

Errors

• error::Error::Git
• error::Error::RevParseFailure

Examples

use radicle_surf::file_system::{Label, SystemType};
use radicle_surf::file_system::unsound;
use radicle_surf::vcs::git::{Browser, Branch, Oid, Repository};
use std::str::FromStr;

let repo = Repository::new("./data/git-platinum")?;
let mut browser = Browser::new(&repo, Branch::local("master"))?;

browser.rev(Branch::remote("dev", "origin"))?;

let directory = browser.get_directory()?;
let mut directory_contents = directory.list_directory();
directory_contents.sort();

assert!(directory_contents.contains(
    &SystemType::file(unsound::label::new("here-we-are-on-a-dev-branch.lol"))
));

pub fn oid(&self, oid: &str) -> Result<Oid, Error>

Parse an Oid from the given string. This is useful if we have a shorthand version of the Oid, as opposed to the full one.

Examples

use radicle_surf::vcs::git::{Branch, Browser, Oid, Repository};
use std::str::FromStr;

let repo = Repository::new("./data/git-platinum")?;
let mut browser = Browser::new(&repo, Branch::local("master"))?;

// Set to the initial commit
let commit = Oid::from_str("e24124b7538658220b5aaf3b6ef53758f0a106dc")?;

assert_eq!(
    commit,
    browser.oid("e24124b")?,
);

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

Get the Diff between two commits.

pub fn initial_diff(&self, oid: Oid) -> Result<Diff, Error>

Get the Diff of a commit with no parents.

pub fn list_branches(&self, filter: RefScope) -> Result<Vec<Branch>, Error>

List the names of the branches that are contained in the underlying Repository.

Errors

• error::Error::Git

Examples

use radicle_surf::vcs::git::{Branch, RefScope, BranchName, Browser, Namespace, Repository};
use std::convert::TryFrom;

let repo = Repository::new("./data/git-platinum")?;
let mut browser = Browser::new(&repo, Branch::local("master"))?;

let branches = browser.list_branches(RefScope::All)?;

// 'master' exists in the list of branches
assert!(branches.contains(&Branch::local("master")));

// Filter the branches by `Remote` 'origin'.
let mut branches = browser.list_branches(RefScope::Remote {
    name: Some("origin".to_string())
})?;
branches.sort();

assert_eq!(branches, vec![
    Branch::remote("HEAD", "origin"),
    Branch::remote("dev", "origin"),
    Branch::remote("master", "origin"),
]);

// Filter the branches by all `Remote`s.
let mut branches = browser.list_branches(RefScope::Remote {
    name: None
})?;
branches.sort();

assert_eq!(branches, vec![
    Branch::remote("HEAD", "origin"),
    Branch::remote("dev", "origin"),
    Branch::remote("master", "origin"),
    Branch::remote("orange/pineapple", "banana"),
    Branch::remote("pineapple", "banana"),
]);

// We can also switch namespaces and list the branches in that namespace.
let golden = browser.switch_namespace(&Namespace::try_from("golden")?, Branch::local("master"))?;

let mut branches = golden.list_branches(RefScope::Local)?;
branches.sort();

assert_eq!(branches, vec![
    Branch::local("banana"),
    Branch::local("master"),
]);

pub fn list_tags(&self, scope: RefScope) -> Result<Vec<Tag>, Error>

List the names of the tags that are contained in the underlying Repository.

Errors

• error::Error::Git

Examples

use radicle_surf::vcs::git::{Branch, RefScope, Browser, Namespace, Oid, Repository, Tag, TagName, Author, Time};
use std::convert::TryFrom;

let repo = Repository::new("./data/git-platinum")?;
let mut browser = Browser::new(&repo, Branch::local("master"))?;

let tags = browser.list_tags(RefScope::Local)?;

assert_eq!(
    tags,
    vec![
        Tag::Light {
            id: Oid::from_str("d3464e33d75c75c99bfb90fa2e9d16efc0b7d0e3")?,
            name: TagName::new("v0.1.0"),
            remote: None,
        },
        Tag::Light {
            id: Oid::from_str("2429f097664f9af0c5b7b389ab998b2199ffa977")?,
            name: TagName::new("v0.2.0"),
            remote: None,
        },
        Tag::Light {
            id: Oid::from_str("19bec071db6474af89c866a1bd0e4b1ff76e2b97")?,
            name: TagName::new("v0.3.0"),
            remote: None,
        },
        Tag::Light {
            id: Oid::from_str("91b69e00cd8e5a07e20942e9e4457d83ce7a3ff1")?,
            name: TagName::new("v0.4.0"),
            remote: None,
        },
        Tag::Light {
            id: Oid::from_str("80ded66281a4de2889cc07293a8f10947c6d57fe")?,
            name: TagName::new("v0.5.0"),
            remote: None,
        },
        Tag::Annotated {
            id: Oid::from_str("4d1f4af2703074d37cb877f4fdbe36322c8e541d")?,
            target_id: Oid::from_str("d6880352fc7fda8f521ae9b7357668b17bb5bad5")?,
            name: TagName::new("v0.6.0"),
            remote: None,
            tagger: Some(Author {
              name: "Thomas Scholtes".to_string(),
              email: "thomas@monadic.xyz".to_string(),
              time: Time::new(1620740737, 120),
            }),
            message: Some("An annotated tag message for v0.6.0\n".to_string())
        },
    ]
);

// We can also switch namespaces and list the branches in that namespace.
let golden = browser.switch_namespace(&Namespace::try_from("golden")?, Branch::local("master"))?;

let branches = golden.list_tags(RefScope::Local)?;
assert_eq!(branches, vec![
    Tag::Light {
        id: Oid::from_str("d3464e33d75c75c99bfb90fa2e9d16efc0b7d0e3")?,
        name: TagName::new("v0.1.0"),
        remote: None,
    },
    Tag::Light {
        id: Oid::from_str("2429f097664f9af0c5b7b389ab998b2199ffa977")?,
        name: TagName::new("v0.2.0"),
        remote: None,
    },
]);
let golden = golden.switch_namespace(&Namespace::try_from("golden")?, Branch::local("master"))?;

let branches = golden.list_tags(RefScope::Remote { name: Some("kickflip".to_string()) })?;
assert_eq!(branches, vec![
    Tag::Light {
        id: Oid::from_str("d3464e33d75c75c99bfb90fa2e9d16efc0b7d0e3")?,
        name: TagName::new("v0.1.0"),
        remote: Some("kickflip".to_string()),
    },
]);

pub fn list_namespaces(&self) -> Result<Vec<Namespace>, Error>

List the namespaces within a Browser, filtering out ones that do not parse correctly.

Errors

• Error::Git

Examples

use radicle_surf::vcs::git::{Branch, BranchType, BranchName, Browser, Namespace, Repository};
use std::convert::TryFrom;

let repo = Repository::new("./data/git-platinum")?;
let mut browser = Browser::new(&repo, Branch::local("master"))?;

let mut namespaces = browser.list_namespaces()?;
namespaces.sort();

assert_eq!(namespaces, vec![
    Namespace::try_from("golden")?,
    Namespace::try_from("golden/silver")?,
    Namespace::try_from("me")?,
]);

pub fn last_commit(&self, path: Path) -> Result<Option<Commit>, Error>

Given a crate::file_system::Path to a file, return the last Commit that touched that file or directory.

Errors

• error::Error::Git
• error::Error::LastCommitException

Examples

use radicle_surf::vcs::git::{Branch, Browser, Oid, Repository};
use radicle_surf::file_system::{Label, Path, SystemType};
use radicle_surf::file_system::unsound;
use std::str::FromStr;

let repo = Repository::new("./data/git-platinum")?;
let mut browser = Browser::new(&repo, Branch::local("master"))?;

// Clamp the Browser to a particular commit
let commit = Oid::from_str("d6880352fc7fda8f521ae9b7357668b17bb5bad5")?;
browser.commit(commit)?;

let head_commit = browser.get().first().clone();
let expected_commit = Oid::from_str("d3464e33d75c75c99bfb90fa2e9d16efc0b7d0e3")?;

let readme_last_commit = browser
    .last_commit(Path::with_root(&[unsound::label::new("README.md")]))?
    .map(|commit| commit.id);

assert_eq!(readme_last_commit, Some(expected_commit));

let expected_commit = Oid::from_str("e24124b7538658220b5aaf3b6ef53758f0a106dc")?;

let memory_last_commit = browser
    .last_commit(Path::with_root(&[unsound::label::new("src"), unsound::label::new("memory.rs")]))?
    .map(|commit| commit.id);

assert_eq!(memory_last_commit, Some(expected_commit));

pub fn file_history(&self, path: Path) -> Result<Vec<Commit>, Error>

Get the commit history for a file or directory.

Examples

use nonempty::NonEmpty;
use radicle_surf::vcs::git::{Branch, Browser, Oid, Repository};
use radicle_surf::file_system::{Label, Path, SystemType};
use radicle_surf::file_system::unsound;
use std::str::FromStr;

let repo = Repository::new("./data/git-platinum")?;
let mut browser = Browser::new(&repo, Branch::local("master"))?;

// Clamp the Browser to a particular commit
let commit = Oid::from_str("223aaf87d6ea62eef0014857640fd7c8dd0f80b5")?;
browser.commit(commit)?;

let root_commits: Vec<Oid> = browser
    .file_history(unsound::path::new("~"))?
    .into_iter()
    .map(|commit| commit.id)
    .collect();

assert_eq!(root_commits,
    vec![
        Oid::from_str("223aaf87d6ea62eef0014857640fd7c8dd0f80b5")?,
        Oid::from_str("80bacafba303bf0cdf6142921f430ff265f25095")?,
        Oid::from_str("a57846bbc8ced6587bf8329fc4bce970eb7b757e")?,
        Oid::from_str("3873745c8f6ffb45c990eb23b491d4b4b6182f95")?,
        Oid::from_str("80ded66281a4de2889cc07293a8f10947c6d57fe")?,
        Oid::from_str("91b69e00cd8e5a07e20942e9e4457d83ce7a3ff1")?,
        Oid::from_str("1820cb07c1a890016ca5578aa652fd4d4c38967e")?,
        Oid::from_str("1e0206da8571ca71c51c91154e2fee376e09b4e7")?,
        Oid::from_str("e24124b7538658220b5aaf3b6ef53758f0a106dc")?,
        Oid::from_str("19bec071db6474af89c866a1bd0e4b1ff76e2b97")?,
        Oid::from_str("f3a089488f4cfd1a240a9c01b3fcc4c34a4e97b2")?,
        Oid::from_str("2429f097664f9af0c5b7b389ab998b2199ffa977")?,
        Oid::from_str("d3464e33d75c75c99bfb90fa2e9d16efc0b7d0e3")?,
    ]
);

let eval_commits: Vec<Oid> = browser
    .file_history(unsound::path::new("~/src/Eval.hs"))?
    .into_iter()
    .map(|commit| commit.id)
    .collect();

assert_eq!(eval_commits,
    vec![
        Oid::from_str("3873745c8f6ffb45c990eb23b491d4b4b6182f95")?,
        Oid::from_str("e24124b7538658220b5aaf3b6ef53758f0a106dc")?,
    ]
);

pub fn extract_signature(
    &self,
    commit: &Commit,
    field: Option<&str>
) -> Result<Option<Signature>, Error>

Extract the signature for a commit

Arguments

• commit - The commit to extract the signature for
• field - the name of the header field containing the signature block; pass None to extract the default ‘gpgsig’

Examples

use radicle_surf::vcs::git::{Branch, Browser, Repository, Oid, error};

let repo = Repository::new("./data/git-platinum")?;
let mut browser = Browser::new(&repo, Branch::local("master"))?;

let commit_with_signature_oid = Oid::from_str(
    "e24124b7538658220b5aaf3b6ef53758f0a106dc"
)?;

browser.commit(commit_with_signature_oid)?;
let history = browser.get();
let commit_with_signature = history.first();
let signature = browser.extract_signature(commit_with_signature, None)?;

// We have a signature
assert!(signature.is_some());

let commit_without_signature_oid = Oid::from_str(
    "80bacafba303bf0cdf6142921f430ff265f25095"
)?;

browser.commit(commit_without_signature_oid)?;
let history = browser.get();
let commit_without_signature = history.first();
let signature = browser.extract_signature(commit_without_signature, None)?;

// There is no signature
assert!(signature.is_none());

pub fn revision_branches(
    &self,
    rev: impl Into<Rev>
) -> Result<Vec<Branch>, Error>

List the Branches, which contain the provided Commit.

Errors

• error::Error::Git

Examples

use radicle_surf::vcs::git::{Browser, Repository, Branch, BranchName, Namespace, Oid};
use std::convert::TryFrom;

let repo = Repository::new("./data/git-platinum")?;
let browser = Browser::new(&repo, Branch::local("master"))?;


let branches = browser.revision_branches(Oid::from_str("27acd68c7504755aa11023300890bb85bbd69d45")?)?;
assert_eq!(
    branches,
    vec![
        Branch::local("dev"),
        Branch::remote("dev", "origin"),
    ]
);

// TODO(finto): I worry that this test will fail as other branches get added
let mut branches = browser.revision_branches(Oid::from_str("1820cb07c1a890016ca5578aa652fd4d4c38967e")?)?;
branches.sort();
assert_eq!(
    branches,
    vec![
        Branch::remote("HEAD", "origin"),
        Branch::local("dev"),
        Branch::remote("dev", "origin"),
        Branch::local("master"),
        Branch::remote("master", "origin"),
        Branch::remote("orange/pineapple", "banana"),
        Branch::remote("pineapple", "banana"),
    ]
);

let golden_browser = browser.switch_namespace(&Namespace::try_from("golden")?,
Branch::local("master"))?;

let branches = golden_browser.revision_branches(Oid::from_str("27acd68c7504755aa11023300890bb85bbd69d45")?)?;
assert_eq!(
    branches,
    vec![
        Branch::local("banana"),
        Branch::remote("fakie/bigspin", "kickflip"),
        Branch::remote("heelflip", "kickflip"),
    ]
);

pub fn get_stats(&self) -> Result<Stats, Error>

Get the Stats of the underlying Repository.

Errors

• error::Error::Git

Examples

use radicle_surf::vcs::git::{Branch, Browser, Repository};

let repo = Repository::new("./data/git-platinum")?;
let mut browser = Browser::new(&repo, Branch::local("master"))?;

let stats = browser.get_stats()?;

assert_eq!(stats.branches, 2);

assert_eq!(stats.commits, 15);

assert_eq!(stats.contributors, 4);

pub fn merge_base(&self, one: Oid, two: Oid) -> Result<Option<Oid>, Error>

Find the best common ancestor between two commits if it exists.

See git2::Repository::merge_base for details.

impl<Repo, A, Error> Browser<Repo, A, Error>

pub fn get(&self) -> History<A> where
    A: Clone, 

Get the current History the Browser is viewing.

pub fn set(&mut self, history: History<A>)

Set the History the Browser should view.

pub fn get_directory(&self) -> Result<Directory, Error>

Render the Directory for this Browser.

pub fn modify<F>(&mut self, f: F) where
    F: Fn(&History<A>) -> History<A>, 

Modify the History in this Browser.

pub fn view_at<F>(&mut self, default_history: History<A>, f: F) where
    A: Clone,
    F: Fn(&History<A>) -> Option<History<A>>, 

Change the Browser’s view of History by modifying it, or using the default History provided if the operation fails.

Trait Implementations

impl<Repo, A, Error> Vcs<A, Error> for Browser<Repo, A, Error> where
    Repo: Vcs<A, Error>, 

type HistoryId = Repo::HistoryId

The way to identify a History.

type ArtefactId = Repo::ArtefactId

The way to identify an artefact.

fn get_history(&self, identifier: Self::HistoryId) -> Result<History<A>, Error>

Find a History in a Repo given a way to identify it

fn get_histories(&self) -> Result<Vec<History<A>>, Error>

Find all histories in a Repo

fn get_identifier(artifact: &A) -> Self::ArtefactId

Identify artefacts of a Repository