| Name | lektor-git-timestamp JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | |
| Summary | Lektor type to deduce page modification time from git |
| upload_time | 2024-02-06 20:56:56 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | Copyright © 2020, 2021, 2023 Geoffrey T. Dairiki
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
lektor
plugin
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Lektor-Git-Timestamp
[](https://pypi.org/project/lektor-git-timestamp/)
[](https://pypi.python.org/pypi/lektor-git-timestamp/)
[](https://github.com/dairiki/lektor-git-timestamp/blob/master/LICENSE)
[](https://github.com/dairiki/lektor-git-timestamp)
[](https://trackgit.com)
This Lektor plugin implements a new datetime-like type,
`gittimestamp`, which gets it's default value from git timestamps.
This can be used to implement auto-updating `pub_date` and `last_mod`
fields in Lektor datamodels.
## Description
The `gittimestamp` type behaves just like the built-in `datetime`
type, except that if the field is left blank in `contents.lr` a
default value will be deduced from git timestamps for the file (or
possibly the file’s filesystem mtime.)
If an explicit value for the field is not found, the git log for the
source file (typically `contents.lr`) is searched using `git log
--follow --remove-empty -- <source_filename>`, and the author
timestamp of all matching commits are considered. Additionally, if
the source file is dirty with respect to git’s HEAD, or if the file is
not checked into the git tree, the file’s mtime is prepended to that
list of timestamps. That list of timestamps is filtered based on the
`ignore_commits` and `skip_first_commit` options (see below); then,
finally, a timestamp is selected from those that remain based on the
setting of the `strategy` option.
### Field Options
The `gittimestamp` type supports the following options.
#### `ignore_commits`
This can be set to a string, which is interpreted as a regular
expression. Any git commits whose commit message matches this pattern
are ignored when computing a default timestamp value for the field.
(The matching is performed using `re.search`.)
#### `skip_first_commit`
If this boolean option is set, the first commit in the git log for the
source file will be ignored. This is useful for implementing a
`last_mod` field which has a defined value only if the source file has
actually been modified since the initial commit.
#### `strategy`
This option determines which timestamp is selected from the git log
(and/or the file mtime). This can be set to one of four values:
- `last`: If the source file is dirty (with respect to the git HEAD
tree), the mtime of the file is used. Otherwise, the timestamp of
the last (nominally the most recent) non-ignored git commit is
used. This is the default strategy.
- `first`: The timestamp of the first (nominally the earliest) commit
is used.
- `latest`: The latest timestamp is used. Normally this produces the same
result at `last`, however due to rebasing, cherry-picking, etc. the git timestamps
may not be monotonically increasing, in which case this option causes the
greatest (most recent) timestamp remaining after any filtering to be selected.
- `earliest`: The earliest timestamp is used. Normally this produces the same
result at `first`, but if the timestamps in the git log are not monotonic,
this will select the minimum of all the timestamps remaining after any filtering.
### Global Configuration
The following global configuration options are supported.
These values are specified by way of the plugins' [configuration file]:
`configs/git-timestamp.ini` under the project site directory.
By default, the [`--follow`][git-log-follow] option is passed to `git log` when
computing timestamps. This behavior may be adjusted on a global basis by way of the plugins' [configuration file] (`configs/git-timestamp.ini` under the project site directory) via the following settings:
#### `follow_renames`
This is a boolean setting that specifies whether the
[`--follow`][git-log-follow] option should be passed to `git log` when
querying git for timestamps. This options causes `git` to attempt to
follow file renames.
Currently, the `follow_renames` is not supported when [Lektor
Alternatives][lektor-alts] are enabled.
If unspecified, `follow_renames` defaults to _false_.
> **Changed** in version 1.0.0b3: The default value for
> `follow_renames` was changed from _true_ to _false_.
> **Note** Since we currently run `git log` on a per-record basis, when `--follow`
> is specified, _copied_ files may be detected as “renamed”. This may not be ideal.
#### `follow_rename_threshold`
Set the _similarity index threshold_ (passed to `git log` via its
[`-M` option][git-log-M]) used when detecting renames. This should be
specified as a (floating point) number between 0 and 100,
inclusive. Setting `follow_rename_threshold = 100` will limit
detection to exact renames only. The default value is 50.
[git-log-M]: https://git-scm.com/docs/git-log#Documentation/git-log.txt--Mltngt
[git-log-follow]: https://git-scm.com/docs/git-log#Documentation/git-log.txt---follow
[configuration file]: https://www.getlektor.com/docs/plugins/howto/#configure-plugins
[lektor-alts]: https://www.getlektor.com/docs/content/alts/
## Examples
Here is a simple example excerpt from a datamodel file:
```ini
<...>
[fields.last_mod]
label = Time last modified
type = gittimestamp
```
On a page using the above datamodel, so long as the `last_mod` field
is left blank in the `contents.lr` file, the page modification time
will be deduced from timestamp of the most recent git commit which
affected that `contents.lr`. (Or if that file is dirty, the value of
`last_mod` will be taken from the file’s filesystem mtime.)
----
Here is a more complicated example which demonstrates the use of all the options.
```ini
<...>
[fields.pub_date]
label = Time first published
type = gittimestamp
strategy = first
[fields.last_mod]
label = Time last modified
type = gittimestamp
ignore_commits = \[nochange\]
skip_first_commit = true
```
This will get the default value of the `pub_date` field from the
timestamp of the first (earliest) git commit for the source file.
The default value for `last_mod` will, as in the previous example, be taken from the
most recent commit for the file, except that:
- any commits whose commit message include the tag `[nochange]` will be ignored
- the first commit (the one whose timestamp is used for `pub_date`) is ignored
If there has only been one commit of the source file, `last_mod` will not have
a default value. (It will evaluate to a jinja2 Undefined instance.)
## Warning: On sorting by `gittimestamp` in `Lektor < 3.3`
A common use case for timestamps is for sorting records.
E.g. in a blog one generally wants to display posts in reverse
chronological order by post date. This generally won't work using
`gittimestamp` timestamps with version of Lektor before 3.3.
The `gittimestamp` type is implemented using a _field
descriptor_. (This is required in order to defer computation of the
field value until after the record for the page is available.) In
`lektor<3.3`, field descriptors are supported for most usages, the
_one glaring exception_ being when sorting records.
This was fixed in Lektor PR
[#789](https://github.com/lektor/lektor/pull/789) which was merged to
the master branch on February 6, 2021, but didn't make it into a release
until Lektor 3.3, released on December 13 2021.
## Author
Jeff Dairiki <dairiki@dairiki.org>
## Changelog
### Release 1.0.0 (2024-02-06)
No code changes from 1.0.0b3
### Release 1.0.0b3 (2024-01-23)
#### Breaking Changes
- Drop support for python 3.8.
- The default value for the `follow_renames` global config setting has
changed from _true_ to _false_.
#### Bugs Fixed
- Fix to work when [alternatives] are enabled. Note that in this case
the `follow_renames` global option is not supported.
#### Testing
- Test under python 3.12.
#### Code Style
- Style: Use [ruff] for style linting and formatting. This replaces
our usage of `black`, `reorder-python-imports`, and `flake8`.
[alternatives]: https://www.getlektor.com/docs/content/alts/
[ruff]: https://docs.astral.sh/ruff/
### Release 1.0.0b2 (2023-06-15)
- Added type annotations.
- Convert packaging to PDM.
#### Code Style
- Style: Run [black] and [reorder-python-imports] on code. Configure
[pre-commit] to keep all up-to-date.
#### Tests
- Disuse the deprecated module `pkg_resources`.
#### Buglets
- Do not strip trailing whitespace from `git log` output. (This was
erroneously removing trailing newlines from the final commit
message.)
[black]: https://github.com/psf/black
[pre-commit]: https://pre-commit.com/
[reorder-python-imports]: https://github.com/asottile/reorder-python-imports
### Release 1.0.0b1 (2023-04-11)
- Drop support for python 2.7 and 3.6. ([#2])
#### Testing
- Test under python 3.10 and 3.11. ([#2])
- Test that `lektor.db.Record.get_sort_key` works with
descriptor-valued fields. (This requires `lektor>=3.3`.)
[#2]: https://github.com/dairiki/lektor-git-timestamp/pull/2
### Release 0.1.0.post1 (2021-08-12)
No code changes.
Add warning to README about `lektor > 3.2` (not yet released) being
required in order to be able to sort records by `gittimestamp` fields.
### Release 0.1 (2021-02-05)
No code changes.
Update development status classifier to "stable".
Add functional tests.
### Release 0.1a2 (2021-02-03)
#### Bugs Fixed
Fixed attrocious typo which prevented the use of anything other than the
default `strategy=last` for picking timestamps.
### Release 0.1a1 (2020-06-16)
Initial release.
Raw data
{
"_id": null,
"home_page": "",
"name": "lektor-git-timestamp",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "Lektor plugin",
"author": "",
"author_email": "Jeff Dairiki <dairiki@dairiki.org>",
"download_url": "https://files.pythonhosted.org/packages/34/4d/e5856a3b6ea138815cba3ad7e32c29ce2281081de7af7223b26a9c3cc652/lektor_git_timestamp-1.0.0.tar.gz",
"platform": null,
"description": "# Lektor-Git-Timestamp\n\n[](https://pypi.org/project/lektor-git-timestamp/)\n[](https://pypi.python.org/pypi/lektor-git-timestamp/)\n[](https://github.com/dairiki/lektor-git-timestamp/blob/master/LICENSE)\n[](https://github.com/dairiki/lektor-git-timestamp)\n[](https://trackgit.com)\n\nThis Lektor plugin implements a new datetime-like type,\n`gittimestamp`, which gets it's default value from git timestamps.\nThis can be used to implement auto-updating `pub_date` and `last_mod`\nfields in Lektor datamodels.\n\n## Description\n\nThe `gittimestamp` type behaves just like the built-in `datetime`\ntype, except that if the field is left blank in `contents.lr` a\ndefault value will be deduced from git timestamps for the file (or\npossibly the file\u2019s filesystem mtime.)\n\nIf an explicit value for the field is not found, the git log for the\nsource file (typically `contents.lr`) is searched using `git log\n--follow --remove-empty -- <source_filename>`, and the author\ntimestamp of all matching commits are considered. Additionally, if\nthe source file is dirty with respect to git\u2019s HEAD, or if the file is\nnot checked into the git tree, the file\u2019s mtime is prepended to that\nlist of timestamps. That list of timestamps is filtered based on the\n`ignore_commits` and `skip_first_commit` options (see below); then,\nfinally, a timestamp is selected from those that remain based on the\nsetting of the `strategy` option.\n\n### Field Options\n\nThe `gittimestamp` type supports the following options.\n\n#### `ignore_commits`\n\nThis can be set to a string, which is interpreted as a regular\nexpression. Any git commits whose commit message matches this pattern\nare ignored when computing a default timestamp value for the field.\n(The matching is performed using `re.search`.)\n\n#### `skip_first_commit`\n\nIf this boolean option is set, the first commit in the git log for the\nsource file will be ignored. This is useful for implementing a\n`last_mod` field which has a defined value only if the source file has\nactually been modified since the initial commit.\n\n#### `strategy`\n\nThis option determines which timestamp is selected from the git log\n(and/or the file mtime). This can be set to one of four values:\n\n- `last`: If the source file is dirty (with respect to the git HEAD\n tree), the mtime of the file is used. Otherwise, the timestamp of\n the last (nominally the most recent) non-ignored git commit is\n used. This is the default strategy.\n\n- `first`: The timestamp of the first (nominally the earliest) commit\n is used.\n\n- `latest`: The latest timestamp is used. Normally this produces the same\n result at `last`, however due to rebasing, cherry-picking, etc. the git timestamps\n may not be monotonically increasing, in which case this option causes the\n greatest (most recent) timestamp remaining after any filtering to be selected.\n\n- `earliest`: The earliest timestamp is used. Normally this produces the same\n result at `first`, but if the timestamps in the git log are not monotonic,\n this will select the minimum of all the timestamps remaining after any filtering.\n\n### Global Configuration\n\nThe following global configuration options are supported.\nThese values are specified by way of the plugins' [configuration file]:\n`configs/git-timestamp.ini` under the project site directory.\n\nBy default, the [`--follow`][git-log-follow] option is passed to `git log` when\ncomputing timestamps. This behavior may be adjusted on a global basis by way of the plugins' [configuration file] (`configs/git-timestamp.ini` under the project site directory) via the following settings:\n\n#### `follow_renames`\n\nThis is a boolean setting that specifies whether the\n[`--follow`][git-log-follow] option should be passed to `git log` when\nquerying git for timestamps. This options causes `git` to attempt to\nfollow file renames.\n\nCurrently, the `follow_renames` is not supported when [Lektor\nAlternatives][lektor-alts] are enabled.\n\nIf unspecified, `follow_renames` defaults to _false_.\n\n> **Changed** in version 1.0.0b3: The default value for\n> `follow_renames` was changed from _true_ to _false_.\n\n> **Note** Since we currently run `git log` on a per-record basis, when `--follow`\n> is specified, _copied_ files may be detected as \u201crenamed\u201d. This may not be ideal.\n\n\n#### `follow_rename_threshold`\n\nSet the _similarity index threshold_ (passed to `git log` via its\n[`-M` option][git-log-M]) used when detecting renames. This should be\nspecified as a (floating point) number between 0 and 100,\ninclusive. Setting `follow_rename_threshold = 100` will limit\ndetection to exact renames only. The default value is 50.\n\n[git-log-M]: https://git-scm.com/docs/git-log#Documentation/git-log.txt--Mltngt\n[git-log-follow]: https://git-scm.com/docs/git-log#Documentation/git-log.txt---follow\n[configuration file]: https://www.getlektor.com/docs/plugins/howto/#configure-plugins\n[lektor-alts]: https://www.getlektor.com/docs/content/alts/\n\n## Examples\n\nHere is a simple example excerpt from a datamodel file:\n\n```ini\n<...>\n\n[fields.last_mod]\nlabel = Time last modified\ntype = gittimestamp\n\n```\n\nOn a page using the above datamodel, so long as the `last_mod` field\nis left blank in the `contents.lr` file, the page modification time\nwill be deduced from timestamp of the most recent git commit which\naffected that `contents.lr`. (Or if that file is dirty, the value of\n`last_mod` will be taken from the file\u2019s filesystem mtime.)\n\n----\n\nHere is a more complicated example which demonstrates the use of all the options.\n\n```ini\n<...>\n\n[fields.pub_date]\nlabel = Time first published\ntype = gittimestamp\nstrategy = first\n\n[fields.last_mod]\nlabel = Time last modified\ntype = gittimestamp\nignore_commits = \\[nochange\\]\nskip_first_commit = true\n\n```\n\nThis will get the default value of the `pub_date` field from the\ntimestamp of the first (earliest) git commit for the source file.\n\nThe default value for `last_mod` will, as in the previous example, be taken from the\nmost recent commit for the file, except that:\n\n- any commits whose commit message include the tag `[nochange]` will be ignored\n- the first commit (the one whose timestamp is used for `pub_date`) is ignored\n\nIf there has only been one commit of the source file, `last_mod` will not have\na default value. (It will evaluate to a jinja2 Undefined instance.)\n\n## Warning: On sorting by `gittimestamp` in `Lektor < 3.3`\n\nA common use case for timestamps is for sorting records.\nE.g. in a blog one generally wants to display posts in reverse\nchronological order by post date. This generally won't work using\n`gittimestamp` timestamps with version of Lektor before 3.3.\n\nThe `gittimestamp` type is implemented using a _field\ndescriptor_. (This is required in order to defer computation of the\nfield value until after the record for the page is available.) In\n`lektor<3.3`, field descriptors are supported for most usages, the\n_one glaring exception_ being when sorting records.\n\nThis was fixed in Lektor PR\n[#789](https://github.com/lektor/lektor/pull/789) which was merged to\nthe master branch on February 6, 2021, but didn't make it into a release\nuntil Lektor 3.3, released on December 13 2021.\n\n## Author\n\nJeff Dairiki <dairiki@dairiki.org>\n\n## Changelog\n\n### Release 1.0.0 (2024-02-06)\n\nNo code changes from 1.0.0b3\n\n### Release 1.0.0b3 (2024-01-23)\n\n#### Breaking Changes\n\n- Drop support for python 3.8.\n- The default value for the `follow_renames` global config setting has\n changed from _true_ to _false_.\n\n#### Bugs Fixed\n\n- Fix to work when [alternatives] are enabled. Note that in this case\n the `follow_renames` global option is not supported.\n\n#### Testing\n\n- Test under python 3.12.\n\n#### Code Style\n\n- Style: Use [ruff] for style linting and formatting. This replaces\n our usage of `black`, `reorder-python-imports`, and `flake8`.\n\n[alternatives]: https://www.getlektor.com/docs/content/alts/\n[ruff]: https://docs.astral.sh/ruff/\n\n### Release 1.0.0b2 (2023-06-15)\n\n- Added type annotations.\n- Convert packaging to PDM.\n\n#### Code Style\n\n- Style: Run [black] and [reorder-python-imports] on code. Configure\n [pre-commit] to keep all up-to-date.\n\n#### Tests\n\n- Disuse the deprecated module `pkg_resources`.\n\n#### Buglets\n\n- Do not strip trailing whitespace from `git log` output. (This was\n erroneously removing trailing newlines from the final commit\n message.)\n\n[black]: https://github.com/psf/black\n[pre-commit]: https://pre-commit.com/\n[reorder-python-imports]: https://github.com/asottile/reorder-python-imports\n\n### Release 1.0.0b1 (2023-04-11)\n\n- Drop support for python 2.7 and 3.6. ([#2])\n\n#### Testing\n\n- Test under python 3.10 and 3.11. ([#2])\n\n- Test that `lektor.db.Record.get_sort_key` works with\n descriptor-valued fields. (This requires `lektor>=3.3`.)\n\n[#2]: https://github.com/dairiki/lektor-git-timestamp/pull/2\n\n\n### Release 0.1.0.post1 (2021-08-12)\n\nNo code changes.\n\nAdd warning to README about `lektor > 3.2` (not yet released) being\nrequired in order to be able to sort records by `gittimestamp` fields.\n\n### Release 0.1 (2021-02-05)\n\nNo code changes.\n\nUpdate development status classifier to \"stable\".\n\nAdd functional tests.\n\n### Release 0.1a2 (2021-02-03)\n\n#### Bugs Fixed\n\nFixed attrocious typo which prevented the use of anything other than the\ndefault `strategy=last` for picking timestamps.\n\n### Release 0.1a1 (2020-06-16)\n\nInitial release.\n",
"bugtrack_url": null,
"license": "Copyright \u00a9 2020, 2021, 2023 Geoffrey T. Dairiki\n \n Permission is hereby granted, free of charge, to any person obtaining\n a copy of this software and associated documentation files (the\n \"Software\"), to deal in the Software without restriction, including\n without limitation the rights to use, copy, modify, merge, publish,\n distribute, sublicense, and/or sell copies of the Software, and to\n permit persons to whom the Software is furnished to do so, subject to\n the following conditions:\n \n The above copyright notice and this permission notice shall be\n included in all copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND,\n EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\n MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\n NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE\n LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION\n OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION\n WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
"summary": "Lektor type to deduce page modification time from git",
"version": "1.0.0",
"project_urls": {
"Home": "https://github.com/dairiki/lektor-git-timestamp"
},
"split_keywords": [
"lektor",
"plugin"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "028cac028b27e7b844977c69d52ba765e4b05b4ff5dd6d507da1f17593778d42",
"md5": "1faef6d6da8b9cf2b850796a9550497a",
"sha256": "af04e0fcbd4e31b340a40703602dacc16d8ff6bcb850b844d618fc2ada95a311"
},
"downloads": -1,
"filename": "lektor_git_timestamp-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1faef6d6da8b9cf2b850796a9550497a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 9387,
"upload_time": "2024-02-06T20:56:55",
"upload_time_iso_8601": "2024-02-06T20:56:55.078899Z",
"url": "https://files.pythonhosted.org/packages/02/8c/ac028b27e7b844977c69d52ba765e4b05b4ff5dd6d507da1f17593778d42/lektor_git_timestamp-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "344de5856a3b6ea138815cba3ad7e32c29ce2281081de7af7223b26a9c3cc652",
"md5": "e2d8513e6e70e04fd3b3220a82b9ea1a",
"sha256": "366a3b06c43ea643749a37cdc433f631de77806290f5a3a13517da1b20a111ef"
},
"downloads": -1,
"filename": "lektor_git_timestamp-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "e2d8513e6e70e04fd3b3220a82b9ea1a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 19506,
"upload_time": "2024-02-06T20:56:56",
"upload_time_iso_8601": "2024-02-06T20:56:56.830879Z",
"url": "https://files.pythonhosted.org/packages/34/4d/e5856a3b6ea138815cba3ad7e32c29ce2281081de7af7223b26a9c3cc652/lektor_git_timestamp-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-06 20:56:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dairiki",
"github_project": "lektor-git-timestamp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "lektor-git-timestamp"
}
