Struct mit_commit::CommitMessage

pub struct CommitMessage { /* fields omitted */ }

A CommitMessage, the primary entry point to the library

Implementations

impl CommitMessage

#[must_use]pub fn from_fragments(
    fragments: Vec<Fragment>,
    scissors: Option<Scissors>
) -> CommitMessage

Convert from fragments back into a full CommitMessage

Get back to a CommitMessage from an ast, usually after you've been editing the text.

Examples

use indoc::indoc;
use mit_commit::{Bodies, CommitMessage, Subject};

let message = CommitMessage::from(indoc!(
    "
    Update bashrc to include kubernetes completions

    This should make it easier to deploy things for the developers.
    Benchmarked with Hyperfine, no noticable performance decrease.

    ; Bitte geben Sie eine Commit-Beschreibung f\u{00FC}r Ihre \u{00E4}nderungen ein. Zeilen,
    ; die mit ';' beginnen, werden ignoriert, und eine leere Beschreibung
    ; bricht den Commit ab.
    ;
    ; Datum:            Sat Jun 27 21:40:14 2020 +0200
    ;
    ; Auf Branch master
    ;
    ; Initialer Commit
    ;
    ; Zum Commit vorgemerkte \u{00E4}nderungen:
    ;    neue Datei:     .bashrc
    ;"
));
assert_eq!(
    CommitMessage::from_fragments(message.get_ast(), message.get_scissors()),
    message,
)

#[must_use]pub fn insert_after_last_full_body(&self, fragment: Fragment) -> CommitMessage

Insert text in the place you're most likely to want it

In case you don't have any full bodies in there, it inserts it at the top of the commit in the subject line.

Examples

use mit_commit::{Fragment, Body, CommitMessage, Comment};

        let ast: Vec<Fragment> = vec![
            Fragment::Body(Body::from("Add file")),
            Fragment::Body(Body::default()),
            Fragment::Body(Body::from("Looks-like-a-trailer: But isn\'t")),
            Fragment::Body(Body::default()),
            Fragment::Body(Body::from("This adds file primarily for demonstration purposes. It might not be\nuseful as an actual commit, but it\'s very useful as a example to use in\ntests.")),
            Fragment::Body(Body::default()),
            Fragment::Body(Body::from("Relates-to: #128")),
            Fragment::Body(Body::default()),
            Fragment::Comment(Comment::from("# Short (50 chars or less) summary of changes\n#\n# More detailed explanatory text, if necessary.  Wrap it to\n# about 72 characters or so.  In some contexts, the first\n# line is treated as the subject of an email and the rest of\n# the text as the body.  The blank line separating the\n# summary from the body is critical (unless you omit the body\n# entirely); tools like rebase can get confused if you run\n# the two together.\n#\n# Further paragraphs come after blank lines.\n#\n#   - Bullet points are okay, too\n#\n#   - Typically a hyphen or asterisk is used for the bullet,\n#     preceded by a single space, with blank lines in\n#     between, but conventions vary here")),
            Fragment::Body(Body::default()),
            Fragment::Comment(Comment::from("# Bitte geben Sie eine Commit-Beschreibung f\u{fc}r Ihre \u{e4}nderungen ein. Zeilen,\n# die mit \'#\' beginnen, werden ignoriert, und eine leere Beschreibung\n# bricht den Commit ab.\n#\n# Auf Branch main\n# Ihr Branch ist auf demselben Stand wie \'origin/main\'.\n#\n# Zum Commit vorgemerkte \u{e4}nderungen:\n#\tneue Datei:     file\n#"))
        ];
        let commit = CommitMessage::from_fragments(ast, None);

        assert_eq!(commit.insert_after_last_full_body(Fragment::Body(Body::from("Relates-to: #656"))).get_ast(), vec![
            Fragment::Body(Body::from("Add file")),
            Fragment::Body(Body::default()),
            Fragment::Body(Body::from("Looks-like-a-trailer: But isn\'t")),
            Fragment::Body(Body::default()),
            Fragment::Body(Body::from("This adds file primarily for demonstration purposes. It might not be\nuseful as an actual commit, but it\'s very useful as a example to use in\ntests.")),
            Fragment::Body(Body::default()),
            Fragment::Body(Body::from("Relates-to: #128\nRelates-to: #656")),
            Fragment::Body(Body::default()),
            Fragment::Comment(Comment::from("# Short (50 chars or less) summary of changes\n#\n# More detailed explanatory text, if necessary.  Wrap it to\n# about 72 characters or so.  In some contexts, the first\n# line is treated as the subject of an email and the rest of\n# the text as the body.  The blank line separating the\n# summary from the body is critical (unless you omit the body\n# entirely); tools like rebase can get confused if you run\n# the two together.\n#\n# Further paragraphs come after blank lines.\n#\n#   - Bullet points are okay, too\n#\n#   - Typically a hyphen or asterisk is used for the bullet,\n#     preceded by a single space, with blank lines in\n#     between, but conventions vary here")),
            Fragment::Body(Body::default()),
            Fragment::Comment(Comment::from("# Bitte geben Sie eine Commit-Beschreibung f\u{fc}r Ihre \u{e4}nderungen ein. Zeilen,\n# die mit \'#\' beginnen, werden ignoriert, und eine leere Beschreibung\n# bricht den Commit ab.\n#\n# Auf Branch main\n# Ihr Branch ist auf demselben Stand wie \'origin/main\'.\n#\n# Zum Commit vorgemerkte \u{e4}nderungen:\n#\tneue Datei:     file\n#"))
        ])

#[must_use]pub fn get_subject(&self) -> Subject

Get the Subject line from the CommitMessage

It's possible to get this from the ast, but it's a bit of a faff, so this is a convencience method

Examples

use indoc::indoc;
use mit_commit::{Bodies, CommitMessage, Subject};

let message = CommitMessage::from(indoc!(
    "
    Update bashrc to include kubernetes completions

    This should make it easier to deploy things for the developers.
    Benchmarked with Hyperfine, no noticable performance decrease.

    ; Bitte geben Sie eine Commit-Beschreibung f\u{00FC}r Ihre \u{00E4}nderungen ein. Zeilen,
    ; die mit ';' beginnen, werden ignoriert, und eine leere Beschreibung
    ; bricht den Commit ab.
    ;
    ; Datum:            Sat Jun 27 21:40:14 2020 +0200
    ;
    ; Auf Branch master
    ;
    ; Initialer Commit
    ;
    ; Zum Commit vorgemerkte \u{00E4}nderungen:
    ;    neue Datei:     .bashrc
    ;"
));
assert_eq!(
    message.get_subject(),
    Subject::from("Update bashrc to include kubernetes completions")
)

#[must_use]pub fn get_ast(&self) -> Vec<Fragment>

Get the underlying data structure that represents the CommitMessage

This is the underlying datastructure for the commit. You might want this to create a complicated linter, or modify the CommitMessage to your liking.

Notice how it doesn't include the Scissors section.

Examples

use indoc::indoc;
use mit_commit::{Body, CommitMessage, Fragment, Trailer, Trailers, Comment};

let message = CommitMessage::from(indoc!(
    "
    Add file

    Looks-like-a-trailer: But isn't

    This adds file primarily for demonstration purposes. It might not be
    useful as an actual commit, but it's very useful as a example to use in
    tests.

    Relates-to: #128
    Relates-to: #129

    ; Short (50 chars or less) summary of changes
    ;
    ; More detailed explanatory text, if necessary.  Wrap it to
    ; about 72 characters or so.  In some contexts, the first
    ; line is treated as the subject of an email and the rest of
    ; the text as the body.  The blank line separating the
    ; summary from the body is critical (unless you omit the body
    ; entirely); tools like rebase can get confused if you run
    ; the two together.
    ;
    ; Further paragraphs come after blank lines.
    ;
    ;   - Bullet points are okay, too
    ;
    ;   - Typically a hyphen or asterisk is used for the bullet,
    ;     preceded by a single space, with blank lines in
    ;     between, but conventions vary here

    ; Bitte geben Sie eine Commit-Beschreibung f\u{00FC}r Ihre \u{00E4}nderungen ein. Zeilen,
    ; die mit ';' beginnen, werden ignoriert, und eine leere Beschreibung
    ; bricht den Commit ab.
    ;
    ; Auf Branch main
    ; Ihr Branch ist auf demselben Stand wie 'origin/main'.
    ;
    ; Zum Commit vorgemerkte \u{00E4}nderungen:
    ;   neue Datei:     file
    ;
    ; ------------------------ >8 ------------------------
    ; \u{00E4}ndern oder entfernen Sie nicht die obige Zeile.
    ; Alles unterhalb von ihr wird ignoriert.
    diff --git a/file b/file
    new file mode 100644
    index 0000000..e69de29
    "
));
let ast = vec![
    Fragment::Body(Body::from("Add file")),
    Fragment::Body(Body::default()),
    Fragment::Body(Body::from("Looks-like-a-trailer: But isn't")),
    Fragment::Body(Body::default()),
    Fragment::Body(Body::from("This adds file primarily for demonstration purposes. It might not be\nuseful as an actual commit, but it\'s very useful as a example to use in\ntests.")),
    Fragment::Body(Body::default()),
    Fragment::Body(Body::from("Relates-to: #128\nRelates-to: #129")),
    Fragment::Body(Body::default()),
    Fragment::Comment(Comment::from("; Short (50 chars or less) summary of changes\n;\n; More detailed explanatory text, if necessary.  Wrap it to\n; about 72 characters or so.  In some contexts, the first\n; line is treated as the subject of an email and the rest of\n; the text as the body.  The blank line separating the\n; summary from the body is critical (unless you omit the body\n; entirely); tools like rebase can get confused if you run\n; the two together.\n;\n; Further paragraphs come after blank lines.\n;\n;   - Bullet points are okay, too\n;\n;   - Typically a hyphen or asterisk is used for the bullet,\n;     preceded by a single space, with blank lines in\n;     between, but conventions vary here")),
    Fragment::Body(Body::default()),
    Fragment::Comment(Comment::from("; Bitte geben Sie eine Commit-Beschreibung für Ihre änderungen ein. Zeilen,\n; die mit \';\' beginnen, werden ignoriert, und eine leere Beschreibung\n; bricht den Commit ab.\n;\n; Auf Branch main\n; Ihr Branch ist auf demselben Stand wie \'origin/main\'.\n;\n; Zum Commit vorgemerkte änderungen:\n;   neue Datei:     file\n;"))
];
assert_eq!(message.get_ast(), ast)

#[must_use]pub fn get_body(&self) -> Bodies

Get the Bodies from the CommitMessage

This gets the bodies from the commit message in easy to use paragraphs, we add in blank bodies because starting a new paragraph is a visual delimiter so we want to make that easy to detect.

It doesn't include the Subject line, but if there's a blank line after it (as is recommended by the manual), the bodies will start with a new empty body.

Examples

use indoc::indoc;
use mit_commit::{Bodies, Body, CommitMessage, Subject};

let message = CommitMessage::from(indoc!(
    "
    Update bashrc to include kubernetes completions

    This should make it easier to deploy things for the developers.
    Benchmarked with Hyperfine, no noticable performance decrease.

    I am unsure as to why this wasn't being automatically discovered from Brew.
    I've filed a bug report with them.

    ; Bitte geben Sie eine Commit-Beschreibung f\u{00FC}r Ihre \u{00E4}nderungen ein. Zeilen,
    ; die mit ';' beginnen, werden ignoriert, und eine leere Beschreibung
    ; bricht den Commit ab.
    ;
    ; Datum:            Sat Jun 27 21:40:14 2020 +0200
    ;
    ; Auf Branch master
    ;
    ; Initialer Commit
    ;
    ; Zum Commit vorgemerkte \u{00E4}nderungen:
    ;    neue Datei:     .bashrc
    ;"
));
let bodies = vec![
    Body::default(),
    Body::from(indoc!(
        "
        This should make it easier to deploy things for the developers.
        Benchmarked with Hyperfine, no noticable performance decrease."
    )),
    Body::default(),
    Body::from(indoc!(
        "
        I am unsure as to why this wasn't being automatically discovered from Brew.
        I've filed a bug report with them."
    )),
];
assert_eq!(message.get_body(), Bodies::from(bodies))

#[must_use]pub fn get_comments(&self) -> Comments

Get the Comments from the CommitMessage

We this will get you all the comments before the Scissors section. The Scissors section is the bit that appears when you run git commit --verbose, that contains the diffs.

If there's Comment mixed in with the body, it'll return those too, but not any of the Body aound them.

Examples

use indoc::indoc;
use mit_commit::{Body, Comment, Comments, CommitMessage, Subject};

let message = CommitMessage::from(indoc!(
    "
    Update bashrc to include kubernetes completions

    This should make it easier to deploy things for the developers.
    Benchmarked with Hyperfine, no noticable performance decrease.

    I am unsure as to why this wasn't being automatically discovered from Brew.
    I've filed a bug report with them.

    ; Bitte geben Sie eine Commit-Beschreibung f\u{00FC}r Ihre \u{00E4}nderungen ein. Zeilen,
    ; die mit ';' beginnen, werden ignoriert, und eine leere Beschreibung
    ; bricht den Commit ab.
    ;
    ; Datum:            Sat Jun 27 21:40:14 2020 +0200
    ;
    ; Auf Branch master
    ;
    ; Initialer Commit
    ;
    ; Zum Commit vorgemerkte \u{00E4}nderungen:
    ;    neue Datei:     .bashrc
    ;"
));
let comments = vec![Comment::from(indoc!(
    "
    ; Bitte geben Sie eine Commit-Beschreibung f\u{00FC}r Ihre \u{00E4}nderungen ein. Zeilen,
    ; die mit ';' beginnen, werden ignoriert, und eine leere Beschreibung
    ; bricht den Commit ab.
    ;
    ; Datum:            Sat Jun 27 21:40:14 2020 +0200
    ;
    ; Auf Branch master
    ;
    ; Initialer Commit
    ;
    ; Zum Commit vorgemerkte \u{00E4}nderungen:
    ;    neue Datei:     .bashrc
    ;"
))];
assert_eq!(message.get_comments(), Comments::from(comments))

#[must_use]pub fn get_scissors(&self) -> Option<Scissors>

Get the Scissors from the CommitMessage

We this will get you all the comments in the Scissors section. The Scissors section is the bit that appears when you run git commit --verbose, that contains the diffs, and is not preserved when you save the commit.

Examples

use indoc::indoc;
use mit_commit::{Body, CommitMessage, Scissors, Subject};

let message = CommitMessage::from(indoc!(
    "
    Add file

    This adds file primarily for demonstration purposes. It might not be
    useful as an actual commit, but it's very useful as a example to use in
    tests.

    Relates-to: #128

    ; Short (50 chars or less) summary of changes
    ;
    ; More detailed explanatory text, if necessary.  Wrap it to
    ; about 72 characters or so.  In some contexts, the first
    ; line is treated as the subject of an email and the rest of
    ; the text as the body.  The blank line separating the
    ; summary from the body is critical (unless you omit the body
    ; entirely); tools like rebase can get confused if you run
    ; the two together.
    ;
    ; Further paragraphs come after blank lines.
    ;
    ;   - Bullet points are okay, too
    ;
    ;   - Typically a hyphen or asterisk is used for the bullet,
    ;     preceded by a single space, with blank lines in
    ;     between, but conventions vary here

    ; Bitte geben Sie eine Commit-Beschreibung f\u{00FC}r Ihre \u{00E4}nderungen ein. Zeilen,
    ; die mit ';' beginnen, werden ignoriert, und eine leere Beschreibung
    ; bricht den Commit ab.
    ;
    ; Auf Branch main
    ; Ihr Branch ist auf demselben Stand wie 'origin/main'.
    ;
    ; Zum Commit vorgemerkte \u{00E4}nderungen:
    ;   neue Datei:     file
    ;
    ; ------------------------ >8 ------------------------
    ; \u{00E4}ndern oder entfernen Sie nicht die obige Zeile.
    ; Alles unterhalb von ihr wird ignoriert.
    diff --git a/file b/file
    new file mode 100644
    index 0000000..e69de29
    "
));
let scissors = Scissors::from(indoc!(
    "
    ; ------------------------ >8 ------------------------
    ; \u{00E4}ndern oder entfernen Sie nicht die obige Zeile.
    ; Alles unterhalb von ihr wird ignoriert.
    diff --git a/file b/file
    new file mode 100644
    index 0000000..e69de29
    "
));
assert_eq!(message.get_scissors(), Some(scissors))

#[must_use]pub fn get_trailers(&self) -> Trailers

Get the Scissors from the CommitMessage

We this will get you all the comments in the Scissors section. The Scissors section is the bit that appears when you run git commit --verbose, that contains the diffs, and is not preserved when you save the commit.

Examples

use indoc::indoc;
use mit_commit::{Body, CommitMessage, Trailer, Trailers};

let message = CommitMessage::from(indoc!(
    "
    Add file

    Looks-like-a-trailer: But isn't

    This adds file primarily for demonstration purposes. It might not be
    useful as an actual commit, but it's very useful as a example to use in
    tests.

    Relates-to: #128
    Relates-to: #129

    ; Short (50 chars or less) summary of changes
    ;
    ; More detailed explanatory text, if necessary.  Wrap it to
    ; about 72 characters or so.  In some contexts, the first
    ; line is treated as the subject of an email and the rest of
    ; the text as the body.  The blank line separating the
    ; summary from the body is critical (unless you omit the body
    ; entirely); tools like rebase can get confused if you run
    ; the two together.
    ;
    ; Further paragraphs come after blank lines.
    ;
    ;   - Bullet points are okay, too
    ;
    ;   - Typically a hyphen or asterisk is used for the bullet,
    ;     preceded by a single space, with blank lines in
    ;     between, but conventions vary here

    ; Bitte geben Sie eine Commit-Beschreibung f\u{00FC}r Ihre \u{00E4}nderungen ein. Zeilen,
    ; die mit ';' beginnen, werden ignoriert, und eine leere Beschreibung
    ; bricht den Commit ab.
    ;
    ; Auf Branch main
    ; Ihr Branch ist auf demselben Stand wie 'origin/main'.
    ;
    ; Zum Commit vorgemerkte \u{00E4}nderungen:
    ;   neue Datei:     file
    ;
    ; ------------------------ >8 ------------------------
    ; \u{00E4}ndern oder entfernen Sie nicht die obige Zeile.
    ; Alles unterhalb von ihr wird ignoriert.
    diff --git a/file b/file
    new file mode 100644
    index 0000000..e69de29
    "
));
let trailers = vec![
    Trailer::new("Relates-to", "#128"),
    Trailer::new("Relates-to", "#129"),
];
assert_eq!(message.get_trailers(), Trailers::from(trailers))

pub fn matches_pattern(&self, re: &Regex) -> bool

Does the commit match the saved portions of the commit

This takes a regex and matches it to the visible portions of the commits, so it excludes comments, and everything after the scissors.

Examples

use indoc::indoc;
use mit_commit::CommitMessage;
use regex::Regex;

let commit = CommitMessage::from(indoc!(
    "
    Example Commit Message

    This is an example commit message for linting


    ; Bitte geben Sie eine Commit-Beschreibung f\u{00FC}r Ihre \u{00E4}nderungen ein. Zeilen,
    ; die mit ';' beginnen, werden ignoriert, und eine leere Beschreibung
    ; bricht den Commit ab.
    ;
    ; Auf Branch main
    ; Ihr Branch ist auf demselben Stand wie 'origin/main'.
    ;
    ; Zum Commit vorgemerkte \u{00E4}nderungen:
    ;    neue Datei:     file
    ;
    "
));

let re = Regex::new("[Bb]itte").unwrap();
assert_eq!(commit.matches_pattern(&re), false);

let re = Regex::new("f[o\u{00FC}]r linting").unwrap();
assert_eq!(commit.matches_pattern(&re), true);

let re = Regex::new("[Ee]xample Commit Message").unwrap();
assert_eq!(commit.matches_pattern(&re), true);

Trait Implementations

impl Clone for CommitMessage

fn clone(&self) -> CommitMessage

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for CommitMessage

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

Formats the value using the given formatter.

impl<'_> From<&'_ str> for CommitMessage

fn from(message: &str) -> Self

Create a new CommitMessage

Create a commit message from a string. It's expected that you'll be reading this during some sort of Git Hook

Examples

use indoc::indoc;
use mit_commit::{Bodies, CommitMessage, Subject};

let message = CommitMessage::from(indoc!(
    "
    Update bashrc to include kubernetes completions

    This should make it easier to deploy things for the developers.
    Benchmarked with Hyperfine, no noticable performance decrease.

    ; Bitte geben Sie eine Commit-Beschreibung f\u{00FC}r Ihre \u{00E4}nderungen ein. Zeilen,
    ; die mit ';' beginnen, werden ignoriert, und eine leere Beschreibung
    ; bricht den Commit ab.
    ;
    ; Datum:            Sat Jun 27 21:40:14 2020 +0200
    ;
    ; Auf Branch master
    ;
    ; Initialer Commit
    ;
    ; Zum Commit vorgemerkte \u{00E4}nderungen:
    ;    neue Datei:     .bashrc
    ;"
));
assert_eq!(
    message.get_subject(),
    Subject::from("Update bashrc to include kubernetes completions")
)

impl From<CommitMessage> for String

fn from(commit_message: CommitMessage) -> Self

Performs the conversion.

impl From<String> for CommitMessage

fn from(message: String) -> Self

Performs the conversion.

impl PartialEq<CommitMessage> for CommitMessage

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl StructuralPartialEq for CommitMessage

impl TryFrom<PathBuf> for CommitMessage

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: PathBuf) -> Result<Self, Self::Error>

Performs the conversion.