use anyhow::bail;use gix::{ Exn, bstr::{BStr, BString}, revision::plumbing::{ spec, spec::parse::{ Delegate, delegate, delegate::{PeelTo, ReflogLookup, SiblingBranch, Traversal}, }, },}; pub fn explain(spec: std::ffi::OsString, mut out: impl std::io::Write) -> anyhow::Result<()> { let mut explain = Explain::new(&mut out); let spec = gix::path::os_str_into_bstr(&spec)?; gix::revision::plumbing::spec::parse(spec, &mut explain).map_err(gix::Error::from)?; if let Some(err) = explain.err { bail!(err); } Ok(())} struct Explain<'a> { out: &'a mut dyn std::io::Write, call: usize, ref_name: Option<BString>, oid_prefix: Option<gix::hash::Prefix>, has_implicit_anchor: bool, err: Option<String>,} impl<'a> Explain<'a> { fn new(out: &'a mut impl std::io::Write) -> Self { Explain { out, call: 0, ref_name: None, oid_prefix: None, has_implicit_anchor: false, err: None, } } fn prefix(&mut self) -> Result<(), Exn> { self.call += 1; write!(self.out, "{:02}. ", self.call).ok(); Ok(()) } fn revision_name(&self) -> BString { self.ref_name.clone().unwrap_or_else(|| { self.oid_prefix .expect("parser must have set some object value") .to_string() .into() }) }} impl delegate::Revision for Explain<'_> { fn find_ref(&mut self, name: &BStr) -> Result<(), Exn> { self.prefix()?; self.ref_name = Some(name.into()); writeln!(self.out, "Lookup the '{name}' reference").ok(); Ok(()) } fn disambiguate_prefix( &mut self, prefix: gix::hash::Prefix, hint: Option<delegate::PrefixHint<'_>>, ) -> Result<(), Exn> { self.prefix()?; self.oid_prefix = Some(prefix); writeln!( self.out, "Disambiguate the '{}' object name ({})", prefix, match hint { None => "any object".to_string(), Some(delegate::PrefixHint::MustBeCommit) => "commit".into(), Some(delegate::PrefixHint::DescribeAnchor { ref_name, generation }) => format!("commit {generation} generations in future of reference {ref_name:?}"), } ) .ok(); Ok(()) } fn reflog(&mut self, query: ReflogLookup) -> Result<(), Exn> { self.prefix()?; self.has_implicit_anchor = true; let ref_name: &BStr = self.ref_name.as_ref().map_or_else(|| "HEAD".into(), AsRef::as_ref); match query { ReflogLookup::Entry(no) => writeln!(self.out, "Find entry {no} in reflog of '{ref_name}' reference").ok(), ReflogLookup::Date(time) => writeln!( self.out, "Find entry closest to time {} in reflog of '{}' reference", time.format_or_unix(gix::date::time::format::ISO8601), ref_name ) .ok(), }; Ok(()) } fn nth_checked_out_branch(&mut self, branch_no: usize) -> Result<(), Exn> { self.prefix()?; self.has_implicit_anchor = true; writeln!(self.out, "Find the {branch_no}th checked-out branch of 'HEAD'").ok(); Ok(()) } fn sibling_branch(&mut self, kind: SiblingBranch) -> Result<(), Exn> { self.prefix()?; self.has_implicit_anchor = true; let ref_info = match self.ref_name.as_ref() { Some(ref_name) => format!("'{ref_name}'"), None => "behind 'HEAD'".into(), }; writeln!( self.out, "Lookup the remote '{}' branch of local reference {}", match kind { SiblingBranch::Upstream => "upstream", SiblingBranch::Push => "push", }, ref_info ) .ok(); Ok(()) }} impl delegate::Navigate for Explain<'_> { fn traverse(&mut self, kind: Traversal) -> Result<(), Exn> { self.prefix()?; let name = self.revision_name(); writeln!( self.out, "{}", match kind { Traversal::NthAncestor(no) => format!("Traverse to the {no}. ancestor of revision named '{name}'"), Traversal::NthParent(no) => format!("Select the {no}. parent of revision named '{name}'"), } ) .ok(); Ok(()) } fn peel_until(&mut self, kind: PeelTo<'_>) -> Result<(), Exn> { self.prefix()?; writeln!( self.out, "{}", match kind { PeelTo::ValidObject => "Assure the current object exists".to_string(), PeelTo::RecursiveTagObject => "Follow the current annotated tag until an object is found".into(), PeelTo::ObjectKind(kind) => format!("Peel the current object until it is a {kind}"), PeelTo::Path(path) => format!("Lookup the object at '{path}' from the current tree-ish"), } ) .ok(); Ok(()) } fn find(&mut self, regex: &BStr, negated: bool) -> Result<(), Exn> { self.prefix()?; self.has_implicit_anchor = true; let negate_text = if negated { "does not match" } else { "matches" }; writeln!( self.out, "{}", match self .ref_name .as_ref() .map(ToString::to_string) .or_else(|| self.oid_prefix.map(|p| p.to_string())) { Some(obj_name) => format!( "Follow the ancestry of revision '{obj_name}' until a commit message {negate_text} regex '{regex}'" ), None => format!( "Find the most recent commit from any reference including 'HEAD' that {negate_text} regex '{regex}'" ), } ) .ok(); Ok(()) } fn index_lookup(&mut self, path: &BStr, stage: u8) -> Result<(), Exn> { self.prefix()?; self.has_implicit_anchor = true; writeln!( self.out, "Lookup the index at path '{}' stage {} ({})", path, stage, match stage { 0 => "base", 1 => "ours", 2 => "theirs", _ => unreachable!("BUG: parser assures of that"), } ) .ok(); Ok(()) }} impl delegate::Kind for Explain<'_> { fn kind(&mut self, kind: spec::Kind) -> Result<(), Exn> { self.prefix()?; self.call = 0; writeln!( self.out, "Set revision specification to {} mode", match kind { spec::Kind::RangeBetween => "range", spec::Kind::ReachableToMergeBase => "merge-base", spec::Kind::ExcludeReachable => "exclude", spec::Kind::IncludeReachableFromParents => "include parents", spec::Kind::ExcludeReachableFromParents => "exclude parents", spec::Kind::IncludeReachable => unreachable!("BUG: 'single' mode is implied but cannot be set explicitly"), } ) .ok(); Ok(()) }} impl Delegate for Explain<'_> { fn done(&mut self) -> Result<(), Exn> { if !self.has_implicit_anchor && self.ref_name.is_none() && self.oid_prefix.is_none() { self.err = Some("Incomplete specification lacks its anchor, like a reference or object name".into()); } Ok(()) }}
use anyhow::bail;
use gix::{
Exn,
bstr::{BStr, BString},
revision::plumbing::{
spec,
spec::parse::{
Delegate, delegate,
delegate::{PeelTo, ReflogLookup, SiblingBranch, Traversal},
},
},
};
pub fn explain(spec: std::ffi::OsString, mut out: impl std::io::Write) -> anyhow::Result<()> {
let mut explain = Explain::new(&mut out);
let spec = gix::path::os_str_into_bstr(&spec)?;
gix::revision::plumbing::spec::parse(spec, &mut explain).map_err(gix::Error::from)?;
if let Some(err) = explain.err {
bail!(err);
}
Ok(())
}
struct Explain<'a> {
out: &'a mut dyn std::io::Write,
call: usize,
ref_name: Option<BString>,
oid_prefix: Option<gix::hash::Prefix>,
has_implicit_anchor: bool,
err: Option<String>,
}
impl<'a> Explain<'a> {
fn new(out: &'a mut impl std::io::Write) -> Self {
Explain {
out,
call: 0,
ref_name: None,
oid_prefix: None,
has_implicit_anchor: false,
err: None,
}
}
fn prefix(&mut self) -> Result<(), Exn> {
self.call += 1;
write!(self.out, "{:02}. ", self.call).ok();
Ok(())
}
fn revision_name(&self) -> BString {
self.ref_name.clone().unwrap_or_else(|| {
self.oid_prefix
.expect("parser must have set some object value")
.to_string()
.into()
})
}
}
impl delegate::Revision for Explain<'_> {
fn find_ref(&mut self, name: &BStr) -> Result<(), Exn> {
self.prefix()?;
self.ref_name = Some(name.into());
writeln!(self.out, "Lookup the '{name}' reference").ok();
Ok(())
}
fn disambiguate_prefix(
&mut self,
prefix: gix::hash::Prefix,
hint: Option<delegate::PrefixHint<'_>>,
) -> Result<(), Exn> {
self.prefix()?;
self.oid_prefix = Some(prefix);
writeln!(
self.out,
"Disambiguate the '{}' object name ({})",
prefix,
match hint {
None => "any object".to_string(),
Some(delegate::PrefixHint::MustBeCommit) => "commit".into(),
Some(delegate::PrefixHint::DescribeAnchor { ref_name, generation }) =>
format!("commit {generation} generations in future of reference {ref_name:?}"),
}
)
.ok();
Ok(())
}
fn reflog(&mut self, query: ReflogLookup) -> Result<(), Exn> {
self.prefix()?;
self.has_implicit_anchor = true;
let ref_name: &BStr = self.ref_name.as_ref().map_or_else(|| "HEAD".into(), AsRef::as_ref);
match query {
ReflogLookup::Entry(no) => writeln!(self.out, "Find entry {no} in reflog of '{ref_name}' reference").ok(),
ReflogLookup::Date(time) => writeln!(
self.out,
"Find entry closest to time {} in reflog of '{}' reference",
time.format_or_unix(gix::date::time::format::ISO8601),
ref_name
)
.ok(),
};
Ok(())
}
fn nth_checked_out_branch(&mut self, branch_no: usize) -> Result<(), Exn> {
self.prefix()?;
self.has_implicit_anchor = true;
writeln!(self.out, "Find the {branch_no}th checked-out branch of 'HEAD'").ok();
Ok(())
}
fn sibling_branch(&mut self, kind: SiblingBranch) -> Result<(), Exn> {
self.prefix()?;
self.has_implicit_anchor = true;
let ref_info = match self.ref_name.as_ref() {
Some(ref_name) => format!("'{ref_name}'"),
None => "behind 'HEAD'".into(),
};
writeln!(
self.out,
"Lookup the remote '{}' branch of local reference {}",
match kind {
SiblingBranch::Upstream => "upstream",
SiblingBranch::Push => "push",
},
ref_info
)
.ok();
Ok(())
}
}
impl delegate::Navigate for Explain<'_> {
fn traverse(&mut self, kind: Traversal) -> Result<(), Exn> {
self.prefix()?;
let name = self.revision_name();
writeln!(
self.out,
"{}",
match kind {
Traversal::NthAncestor(no) => format!("Traverse to the {no}. ancestor of revision named '{name}'"),
Traversal::NthParent(no) => format!("Select the {no}. parent of revision named '{name}'"),
}
)
.ok();
Ok(())
}
fn peel_until(&mut self, kind: PeelTo<'_>) -> Result<(), Exn> {
self.prefix()?;
writeln!(
self.out,
"{}",
match kind {
PeelTo::ValidObject => "Assure the current object exists".to_string(),
PeelTo::RecursiveTagObject => "Follow the current annotated tag until an object is found".into(),
PeelTo::ObjectKind(kind) => format!("Peel the current object until it is a {kind}"),
PeelTo::Path(path) => format!("Lookup the object at '{path}' from the current tree-ish"),
}
)
.ok();
Ok(())
}
fn find(&mut self, regex: &BStr, negated: bool) -> Result<(), Exn> {
self.prefix()?;
self.has_implicit_anchor = true;
let negate_text = if negated { "does not match" } else { "matches" };
writeln!(
self.out,
"{}",
match self
.ref_name
.as_ref()
.map(ToString::to_string)
.or_else(|| self.oid_prefix.map(|p| p.to_string()))
{
Some(obj_name) => format!(
"Follow the ancestry of revision '{obj_name}' until a commit message {negate_text} regex '{regex}'"
),
None => format!(
"Find the most recent commit from any reference including 'HEAD' that {negate_text} regex '{regex}'"
),
}
)
.ok();
Ok(())
}
fn index_lookup(&mut self, path: &BStr, stage: u8) -> Result<(), Exn> {
self.prefix()?;
self.has_implicit_anchor = true;
writeln!(
self.out,
"Lookup the index at path '{}' stage {} ({})",
path,
stage,
match stage {
0 => "base",
1 => "ours",
2 => "theirs",
_ => unreachable!("BUG: parser assures of that"),
}
)
.ok();
Ok(())
}
}
impl delegate::Kind for Explain<'_> {
fn kind(&mut self, kind: spec::Kind) -> Result<(), Exn> {
self.prefix()?;
self.call = 0;
writeln!(
self.out,
"Set revision specification to {} mode",
match kind {
spec::Kind::RangeBetween => "range",
spec::Kind::ReachableToMergeBase => "merge-base",
spec::Kind::ExcludeReachable => "exclude",
spec::Kind::IncludeReachableFromParents => "include parents",
spec::Kind::ExcludeReachableFromParents => "exclude parents",
spec::Kind::IncludeReachable =>
unreachable!("BUG: 'single' mode is implied but cannot be set explicitly"),
}
)
.ok();
Ok(())
}
}
impl Delegate for Explain<'_> {
fn done(&mut self) -> Result<(), Exn> {
if !self.has_implicit_anchor && self.ref_name.is_none() && self.oid_prefix.is_none() {
self.err = Some("Incomplete specification lacks its anchor, like a reference or object name".into());
}
Ok(())
}
}