Struct Signature 

pub struct Signature {
    pub name: String,
    pub email: String,
    pub time: OffsetDateTime,
}

Parsed author or committer identity from a full header or reflog identity line.

Fields

name: String

Display name (may be empty).

email: String

Email address inside <…>.

time: OffsetDateTime

Timestamp with the recorded ±HHMM offset preserved.

Implementations

impl Signature

pub fn new( name: impl Into<String>, email: impl Into<String>, time: OffsetDateTime, ) -> Result<Self, SignatureError>

Build a signature for writing into a commit or tag.

Parameters

• name: display name (may be empty).
• email: address written inside <…> (may be empty).
• time: timestamp; its UTC offset becomes the ±HHMM field.

Errors

See Self::validate.

Examples

use grit_lib::ident::Signature;
use time::{OffsetDateTime, UtcOffset};
let time = OffsetDateTime::from_unix_timestamp(1_700_000_000)?
    .to_offset(UtcOffset::from_hms(-8, 0, 0)?);
let sig = Signature::new("Ada Lovelace", "ada@example.com", time)?;
assert_eq!(sig.header_line(), "Ada Lovelace <ada@example.com> 1700000000 -0800");
assert!(Signature::new("Ada <x>", "ada@example.com", time).is_err());

pub fn cleaned( name: &str, email: &str, time: OffsetDateTime, ) -> Result<Self, SignatureError>

Build a signature from a name and email that may hold characters an identity line can’t, cleaning them as Git cleans GIT_AUTHOR_NAME and friends: <, > and control characters other than tab are dropped, and punctuation and whitespace are trimmed from both ends. Use it for identities from untrusted input, such as a request to a server, so nothing in them can end the line early or add a header.

Parameters

• name: display name; empty after cleaning is allowed.
• email: address written inside <…>; empty after cleaning is allowed.
• time: timestamp; its UTC offset becomes the ±HHMM field.

Returns

A signature whose Self::header_line git fsck accepts.

Errors

SignatureError::BeforeEpoch and SignatureError::SubMinuteOffset for a time Self::validate refuses; the name and email always pass.

Examples

use grit_lib::ident::Signature;
use time::OffsetDateTime;
let time = OffsetDateTime::from_unix_timestamp(1_700_000_000)?;
let sig = Signature::cleaned("Eve\nencoding bogus", " <e>v<e@x> ", time)?;
assert_eq!(sig.header_line(), "Eveencoding bogus <eve@x> 1700000000 +0000");

pub fn validate(&self) -> Result<(), SignatureError>

Check that Self::header_line yields an identity line git fsck accepts.

Errors

• SignatureError::ForbiddenCharacter when the name or email contains <, >, or a control character other than tab.
• SignatureError::BeforeEpoch when the time is before 1970-01-01 UTC.
• SignatureError::SubMinuteOffset when the UTC offset has a seconds component, which the ±HHMM field cannot represent.

pub fn reflog_name_email(&self) -> String

Name <email> for a reflog identity column; the timestamp is taken from crate::refs::store::ReflogUpdate::time when the entry is formatted.

pub fn header_line(&self) -> String

Render as a header payload: Name <email> <unix-seconds> <±HHMM>.

The result is what follows author / committer / tagger in an object. It is only fsck-clean when Self::validate succeeds.

pub fn format_rfc3339(&self) -> Option<String>

Format Self::time as RFC 3339 (includes the original offset).

pub fn from_header_lossy(line: &str) -> Self

Parse an identity line as stored in a commit or tag, accepting what git log accepts.

Unlike str::parse, this never fails: a missing <email> leaves Self::email empty with the whole text as the name, and a missing, non-numeric or overflowing date becomes the Unix epoch in UTC, the same sentinel Git shows for such commits.

Parameters

• line: the text after author / committer / tagger in an object header.

Examples

use grit_lib::ident::Signature;

let sig = Signature::from_header_lossy("Ada <ada@example.com> 1700000000 +0100");
assert_eq!(sig.email, "ada@example.com");
assert_eq!(sig.time.unix_timestamp(), 1_700_000_000);

let bogus = Signature::from_header_lossy("Ada <ada@example.com> totally_bogus");
assert_eq!(bogus.time.unix_timestamp(), 0);

Trait Implementations

impl Clone for Signature

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Signature

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for Signature

impl FromStr for Signature

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

Parse a full header identity line (Name <email> <unix-seconds> <±HHMM>).

Errors

SignatureError::Malformed when the line does not have exactly one <email>, has a missing, non-numeric, or overflowing date, or has text after the ±HHMM timezone; otherwise the Signature::validate errors.

type Err = SignatureError

The associated error which can be returned from parsing.

impl PartialEq for Signature

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for Signature