Skip to content

Latest commit

 

History

History
317 lines (250 loc) · 10.8 KB

README.adoc

File metadata and controls

317 lines (250 loc) · 10.8 KB
Raw

Jamal Git Macros

This macro package can fetch information from a local git repository. The package does not support modification of the repository, only reading information from it. The package does not support remote repositories, only local ones.

This macro package is included in the prepackaged versions of Jamal.

To use this module, you have to add the dependency to your Maven project, as:

<dependency>
    <groupId>com.javax0.jamal</groupId>
    <artifactId>jamal-git</artifactId>
    <version>2.8.2-SNAPSHOT</version>
</dependency>

Macros Implemented

git

This macro should be used to specify the directory of the git repository. For example

Jamal source
{@git location=../.git}

will locate the repository and then subsequent macros can fetch information from the repository. The parameter option (parop) location is mandatory and it should point to the .git directory of the repository.

The parameters of the opened repository are stored in the user defined macro $git. You can reference this macro directly as {$git} and the value will always be an empty string.

If you want to handle multiple git repositories, you can use the parop id to give an identifier to the repository. If used, the name specified will be used as a user-defined macro name to store the preference to the git repository. In this case the parop id should be used in all later calls to the git macros using the specific git repository.

git:tag(s), got:branch(es)

This macro can be called as

  • git:tag,

  • git:tags,

  • git:branch, or

  • git:branches

The macro can collect tags or branches from the local git repository. The singular and plural forms behave the same, and they exist to help the readability. The macro names containing tag return a tag or tags, and the ones containing branch return a branch or branches.

The behavior of the macro can be controlled using parops. These are the following:

  • id is the identifier of the opened git repository. The default value is $git which is also the default value of the git:connect macro. If you are not dealing with more than one git repositories, you can omit this parameter. Use it only if you also used it in the git:connect macro.

  • match is a regular expression that the tag name should match. If this parameter is present, then only those tags are listed that match the regular expression.

  • index is the index of the tag to list. If this parameter is present, then only the tag at the index is listed. The index is 0-based. Negative index is also allowed. In this case, the index is counted from the end of the list. For example, -1 means the last tag. If the index is too large or too small, then an error is thrown.

  • last If this parameter is present, then only the last tag is listed. It is the same as index=-1.

  • first If this parameter is present, then only the first tag is listed. It is the same as index=0.

  • single If this parameter is present, then the result is a single tag. If this parameter is present and the result is more than one tag then an error is thrown.

  • The following parameters are exclusive. Only one of them can be used in a macro. The default value is orderByName.

    • orderByName orders the tags by name.

    • orderByDate orders the tags by the commit date.

  • The following parameters are exclusive. Only one of them can be used in a macro. The default value is name.

    • name will return the name(s) of the tag(s) or branch(es).

    • time will return the time of the commit of the tag(s) or branch(es).

    • hash will return the hash of the commit of the tag(s) or branch(es).

  • sep is the separator between the tags. The default value is , (a comma). This string (not only a single character is possible) is used to separate the elements in the result. The list can be used as the value list for the for macro. In the very special case when some of the elements contain a comma, then you can use this parameter.

Examples:

Jamal source
{@git location=../.git}
The latest release of Jamal is {#string:substring (begin=1) {@git:tag last orderByName match=v.*}}.

result in:

output
The latest release of Jamal is 2.8.1.

git:commit(s)

This macro will return one or more commits from the git repository.

  • id is the identifier of the opened git repository. The default value is $git which is also the default value of the git:connect macro. If you are not dealing with more than one git repositories, you can omit this parameter. Use it only if you also used it in the git:connect macro.

  • branch tag or branch is the name of the tag, branch to list. You can use any of them interchangeably. It is not an error to use tag when you list branches or other ways around. If you want to emphasize that the name can be either a tag or a branch, then use ref.

  • ref can be used as an alternative to specifying the name of the branch or tag. You can also specify the hex value of a commit ID to retrieve the values for a single commit. You need to specify at least 4 characters of the commit ID, and it has to be unique. Using at least 7 characters is recommended to avoid ambiguity.

  • from

  • to specify the starting and ending commit tags to list. from is the starting tag, and to is the ending tag. The list will include the commits from the from tag to the to tag. The order of the list is from the latest to the oldest commit.

  • limit is the maximum number of tags to list. Cannot be used when last or index is also present.

  • index is the index of the tag to list. If this parameter is present, then only the tag at the index is listed. The index is 0-based. Negative indices are not allowed. index=0 means the last commit. If the index is too large or negative (would mean future commits), an error is thrown.

  • last If this parameter is present, then only the last tag is listed. It is the same as index=0.

  • The following parameters are exclusive. Only one of them can be used in a macro. The default value is name.

    • hash - The full SHA-1 hash of the commit.

    • abbreviated - The abbreviated SHA-1 hash of the commit.

    • author - The name of the author of the commit.

    • committer - The name of the committer of the commit.

    • date - The author date of the commit (Unix timestamp in seconds since the epoch).

    • commitTime - The commit time (Unix timestamp in seconds since the epoch).

    • message - The full commit message.

    • shortMessage - The short commit message.

    • parentIds - The SHA-1 hashes of the parent commits.

    • treeId - The SHA-1 hash of the tree object associated with the commit.

  • footnote can specify the footnote to use as an output. When this parameter is used, no other output option like has, abbreviated, author, etc. can be used. The output will be the line or lines of the message that follows the footnote line.

  • sep is the separator between the tags. The default value is , (a comma). This string (not only a single character is possible) is used to separate the elements in the result. The list can be used as the value list for the for macro. In the very special case when some of the elements contain a comma, then you can use this parameter.

Note
 There is a separate section detailing how to use the parop footnote. See below!

There are certain restrictions on the commit parameters. You can use some parameters together, while some others are exclusive:

  • footnote and what cannot be used together.

  • You have to specify both from and to or none of them.

  • You cannot specify both last and index.

  • You cannot specify both last and limit.

  • You cannot specify both index and limit.

  • You cannot specify both to and limit.

  • You cannot specify from or to with a commit ID specified using ref.

Examples:

Jamal source
{@git location=../.git}
The latest commit to Jamal is: "{@git:commit branch=master last shortMessage}"

result in:

output
The latest commit to Jamal is: "further fix for the windows failing test"
Jamal source
{@counter:define id=$counter format=%2d start=1 step=1 }
{#range lines=1..11
  {!@for [evalist] $C in ({@git:commit from=1.0.2 to=1.1.0 branch=master hash})=
{$counter}. {@git:commit ref=$C abbreviated}
    {@git:commit ref=$C shortMessage}}}

result in:

output
1. ec34577
   POMs and also jamal macro files were updated
2. 3db268f
   tracing was extended to include warnings test support was also modified to be more readable fixed user defined macro parameter handling in case of lenient and providing too many arguments
3. 473c5d0
   InnerScopeDependent implemented
4. bc7204a
   new extension macros to handle snippets
5. 8a857c1
   documentation was extended explaining that ident eats space

git:commit footnote

The command git:commit can be used to collect the commit message footnotes. The command has to be called with the footnote parop specifying the name of the footnote. Using this command, you can create a list of changes between two releases.

You can add lines to the commit messages starting with a key, like Change-Note. When you use the parop footnote=change-note specifying the name of the key the value will be the text following the key in the commit message.

In the following example we print the footnote my-special and also the full commit message for a specific commit of the Jamal git repository:

Jamal source
message: {@git:commit ref=178bb91 message}
footnote: {@git:commit ref=178bb91 footnote=my-special}

will result in:

output
message: My-Special: sample footnote message message for documentation
Rev: git macro module

footnote: sample footnote message message for documentation

You can add multiline footnotes to the commit messages. When the first line or any continuation line ends with an underscore (_) character the next line will be appended to the footnote. The underscore character and any spaces before are removed from the output. Footnote lines always end with a new line character, even if the commit message is not terminated with one.

git:format

Format a time stamp from the git repository. When some commands like git:commit return a time stamp, you can format it using this macro. The format is the same as the Java SimpleDateFormat format and it has to be specified in the input of the macro. The time stamp is specified in the parop time.

  • time is the time as returned by some of the git commands, in number of seconds since the epoch.

  • tz or timezone is the time zone to use when formatting the time. The default is UTC.

Examples:

Jamal source
{@git:commit ref=178bb91 date}
{#git:format (time={@git:commit ref=178bb91 date}) yyyy-MM-dd HH:mm:ss Z}

will result in:

output
1730127733
2024-10-28 15:02:13 +0000