|
| 1 | +# Quick User Guide |
| 2 | + |
| 3 | +A quick showcase of all functionality. This feature is based on [git-blame](https://git-scm.com/docs/git-blame). |
| 4 | + |
| 5 | +ℹ️ The line author view only works in Live-Preview and Source mode - not in Reading mode. |
| 6 | + |
| 7 | +ℹ️ Currently, only Obsidian on desktop is supported. |
| 8 | + |
| 9 | +ℹ️ The recently released Obsidian v1.0 is fully supported. The images and GIFs in this document are however not yet updated. |
| 10 | + |
| 11 | +## Activate |
| 12 | + |
| 13 | + |
| 14 | + |
| 15 | +It can also be activated via Command Palette `Obsidian Git: Toggle line author information`. |
| 16 | + |
| 17 | +## Default line author information |
| 18 | + |
| 19 | + |
| 20 | + |
| 21 | +Shows the initials of the author as well as the authoring date in `YYYY-MM-DD` format. |
| 22 | + |
| 23 | +The `*` indicates, that the author and committer (or their timestamps) are different - i.e., due to a rebase. |
| 24 | + |
| 25 | +## Commit hash and full name |
| 26 | + |
| 27 | + |
| 28 | + |
| 29 | +via config |
| 30 | + |
| 31 | + |
| 32 | + |
| 33 | +## Natural language dates |
| 34 | + |
| 35 | + |
| 36 | + |
| 37 | +## Custom date formats |
| 38 | + |
| 39 | + |
| 40 | + |
| 41 | +via config |
| 42 | + |
| 43 | + |
| 44 | + |
| 45 | +## Commit time in local/author/UTC time-zone |
| 46 | + |
| 47 | +**UTC+0000/Z** |
| 48 | + |
| 49 | +The simplest option to start with is showing the time in `UTC+00:00/Z` time-zone. |
| 50 | +This is independent of both your local and the author's time-zone. |
| 51 | +It is shown with a suffix `Z` to avoid confusion with local time. |
| 52 | + |
| 53 | + |
| 54 | + |
| 55 | +This is the time displayed in the guter is the same for all users. |
| 56 | + |
| 57 | +**My local (default)** |
| 58 | + |
| 59 | +By default, the times are shown in your local time-zone - i.e., `What was the clock-time at my wall showing, when the commit was made?` This depends on your local time-zone. For instance, this is the view for a user in the `UTC+01:00` time-zone. |
| 60 | + |
| 61 | + |
| 62 | + |
| 63 | +Note, how the displayed time is `1h` ahead of the above `UTC+0000` time. |
| 64 | + |
| 65 | +**Author's local** |
| 66 | + |
| 67 | +Alternatively, it can show it in the author's time-zone with explicit `UTC` offset - i.e., `What was clock-time at the author's wall and their explicit UTC offset, when the commit was made?` |
| 68 | + |
| 69 | +This is independent of your local time-zone and the same time is displayed for all users. |
| 70 | + |
| 71 | + |
| 72 | + |
| 73 | +**Configuration** |
| 74 | + |
| 75 | + |
| 76 | + |
| 77 | +## Age-based gutter colors |
| 78 | + |
| 79 | +The line gutter color is based on the age of the commit. It adapts to the dark/light mode automatically. |
| 80 | + |
| 81 | + |
| 82 | + |
| 83 | +Red-ish means newer and blue-ish means older. All commits at and above a certain maximum coloring |
| 84 | +age (configurable; default `1 year`) get the same strongest blue-ish color. |
| 85 | + |
| 86 | +The colors are configurable and the defaults are chosen to be accessible. |
| 87 | + |
| 88 | + |
| 89 | + |
| 90 | +## Adjust text color CSS based on theme |
| 91 | + |
| 92 | +By default, the gutter text color uses `var(--text-muted)` which |
| 93 | +is whatever is defined by your theme. You can however, change it to a different CSS |
| 94 | +color or variable. |
| 95 | + |
| 96 | + |
| 97 | + |
| 98 | +Example: |
| 99 | +| `var(--text-muted)` | `var(--text-normal)` | |
| 100 | +|----------------------------------------------|-----------------------------------------------| |
| 101 | +|  |  | |
| 102 | + |
| 103 | +## Copy commit hash |
| 104 | + |
| 105 | + |
| 106 | + |
| 107 | +## Quick configure gutter |
| 108 | + |
| 109 | + |
| 110 | + |
| 111 | +## New/uncommitted lines and files show `+++` |
| 112 | + |
| 113 | + |
| 114 | + |
| 115 | +## Follow lines across cut-copy-paste-ing within same commit / all commits |
| 116 | + |
| 117 | +By default, each line shows the last commit, where it was changed. |
| 118 | +This means, that cut-copy-paste-ing lines will show the new commit, |
| 119 | +even though it was not originally written in that commit. |
| 120 | + |
| 121 | + |
| 122 | + |
| 123 | +However, if for instance following is set to `all commits`, then this is the result: |
| 124 | + |
| 125 | + |
| 126 | + |
| 127 | +Configuration: |
| 128 | + |
| 129 | + |
| 130 | + |
| 131 | +## Soft and unintrusive ansynchronous view updates |
| 132 | + |
| 133 | +Since computing the line author information takes time (due to a `git blame` shell invocation) |
| 134 | +the result appears delayed. To minimize distraction and improve user experience, |
| 135 | +the view is updated in a soft and unintrusive manner. |
| 136 | + |
| 137 | +When opening a file, a placeholder is shown meanwhile: |
| 138 | + |
| 139 | + |
| 140 | + |
| 141 | +While editing, a placeholder is shown as well until the file is saved and the line author information is computed. |
| 142 | + |
| 143 | + |
| 144 | + |
| 145 | +## Multi-line block support |
| 146 | + |
| 147 | +The markdown rendering of multiple lines as a combined block is also supported. |
| 148 | +In this case the newest of all lines is shown in the gutter. |
| 149 | + |
| 150 | + |
| 151 | + |
| 152 | +## Ignore whitespace and newlines |
| 153 | + |
| 154 | +This can be activated in the settings. |
| 155 | + |
| 156 | +| **Original** | **Changed with preserved whitespace** | **Changed with ignored whitespace** | |
| 157 | +|------------------------------------------------------|-------------------------------------------------------|-------------------------------------------------------| |
| 158 | +|  |  |  | |
| 159 | + |
| 160 | +Note, how ignoring the whitespace does not mark the indented |
| 161 | +lines as changes, as only additional whitespace was added. |
| 162 | + |
| 163 | +## Submodules support |
| 164 | + |
| 165 | +Line author information is fully supported in submodules. |
0 commit comments