git-vidi 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,162 @@
1
+ .TH GIT-VIDI 1 "" "vidi" "vidi manual"
2
+ .SH NAME
3
+ vidi, git\-view, git\-vidi \- browse a local git repository in the terminal
4
+ .SH SYNOPSIS
5
+ .B git\-vidi [\-h] [\-\-version] [repo_dir]
6
+ .SH DESCRIPTION
7
+ Opens the repository you are in when given no path. Settings such as the theme and the language scan are changed inside the app from the command palette (Ctrl+P). The same program runs as vidi, git view and git vidi.
8
+ .SH OPTIONS
9
+ .TP
10
+ .B \-h, \-\-help
11
+ show this help message and exit
12
+ .TP
13
+ .B \-\-version
14
+ show program's version number and exit
15
+ .TP
16
+ .B repo_dir
17
+ Path inside a local git repository (defaults to the current folder)
18
+ .SH KEYS
19
+ Press ? in the app to show these keys.
20
+ .SS Main screen
21
+ .TP
22
+ .B j / k or up / down
23
+ Move within the focused panel
24
+ .TP
25
+ .B tab / shift+tab
26
+ Switch between panels
27
+ .TP
28
+ .B enter
29
+ Open the commit, or the highlighted language's files
30
+ .TP
31
+ .B f
32
+ Browse the highlighted commit's files
33
+ .TP
34
+ .B /
35
+ Filter the commit table (esc clears)
36
+ .TP
37
+ .B left / right
38
+ Previous / next language, or back / forward a week on the graph
39
+ .TP
40
+ .B h / l
41
+ Select the older / newer active day
42
+ .TP
43
+ .B [ / ]
44
+ Step through years
45
+ .TP
46
+ .B r
47
+ Cycle the date range
48
+ .TP
49
+ .B b
50
+ Pick a branch
51
+ .TP
52
+ .B ?
53
+ Show the key reference
54
+ .TP
55
+ .B q
56
+ Quit
57
+ .SS Commit detail
58
+ .TP
59
+ .B j / k or up / down
60
+ Move within the focused pane
61
+ .TP
62
+ .B tab / shift+tab
63
+ Switch between panes
64
+ .TP
65
+ .B [ / ]
66
+ Previous / next commit
67
+ .TP
68
+ .B p
69
+ Toggle file diff and full patch
70
+ .TP
71
+ .B f
72
+ Browse this commit's files
73
+ .TP
74
+ .B /
75
+ Filter the files list, or search the patch
76
+ .TP
77
+ .B enter / shift+enter
78
+ Next / previous patch match while searching
79
+ .TP
80
+ .B n / N
81
+ Next / previous patch match
82
+ .TP
83
+ .B left / right
84
+ Scroll the patch sideways when lines are not wrapped
85
+ .TP
86
+ .B page up / page down
87
+ Scroll by a page
88
+ .TP
89
+ .B home / end
90
+ Jump to the top or bottom
91
+ .TP
92
+ .B drag / ctrl+c
93
+ Select patch text with the mouse, then copy it
94
+ .TP
95
+ .B esc / q
96
+ Back (esc first closes the search)
97
+ .SS Branch picker
98
+ .TP
99
+ .B type
100
+ Filter the branch list
101
+ .TP
102
+ .B up / down
103
+ Move the highlight
104
+ .TP
105
+ .B enter
106
+ Switch to the highlighted branch
107
+ .TP
108
+ .B esc / q
109
+ Cancel
110
+ .SS Commit files
111
+ .TP
112
+ .B j / k or up / down
113
+ Move between files
114
+ .TP
115
+ .B /
116
+ Filter the list (esc clears)
117
+ .TP
118
+ .B [ / ]
119
+ Previous / next commit
120
+ .TP
121
+ .B enter
122
+ Open the highlighted file
123
+ .TP
124
+ .B esc / q
125
+ Back
126
+ .SS File view
127
+ .TP
128
+ .B j / k or up / down
129
+ Scroll (arrows scroll even while searching)
130
+ .TP
131
+ .B /
132
+ Search in the file
133
+ .TP
134
+ .B enter / shift+enter
135
+ Next / previous match while searching
136
+ .TP
137
+ .B n / N
138
+ Next / previous match
139
+ .TP
140
+ .B left / right
141
+ Scroll sideways when lines are not wrapped
142
+ .TP
143
+ .B [ / ]
144
+ Previous / next file
145
+ .TP
146
+ .B page up / page down
147
+ Scroll by a page
148
+ .TP
149
+ .B home / end
150
+ Jump to the top or bottom
151
+ .TP
152
+ .B drag / ctrl+c
153
+ Select text with the mouse, then copy it
154
+ .TP
155
+ .B esc / q
156
+ Back (esc first closes the search)
157
+ .SH FILES
158
+ .TP
159
+ .I ~/.config/vidi/config.json
160
+ Saved preferences (honors XDG_CONFIG_HOME).
161
+ .SH SEE ALSO
162
+ .BR git (1)
@@ -0,0 +1,162 @@
1
+ .TH GIT-VIEW 1 "" "vidi" "vidi manual"
2
+ .SH NAME
3
+ vidi, git\-view, git\-vidi \- browse a local git repository in the terminal
4
+ .SH SYNOPSIS
5
+ .B git\-view [\-h] [\-\-version] [repo_dir]
6
+ .SH DESCRIPTION
7
+ Opens the repository you are in when given no path. Settings such as the theme and the language scan are changed inside the app from the command palette (Ctrl+P). The same program runs as vidi, git view and git vidi.
8
+ .SH OPTIONS
9
+ .TP
10
+ .B \-h, \-\-help
11
+ show this help message and exit
12
+ .TP
13
+ .B \-\-version
14
+ show program's version number and exit
15
+ .TP
16
+ .B repo_dir
17
+ Path inside a local git repository (defaults to the current folder)
18
+ .SH KEYS
19
+ Press ? in the app to show these keys.
20
+ .SS Main screen
21
+ .TP
22
+ .B j / k or up / down
23
+ Move within the focused panel
24
+ .TP
25
+ .B tab / shift+tab
26
+ Switch between panels
27
+ .TP
28
+ .B enter
29
+ Open the commit, or the highlighted language's files
30
+ .TP
31
+ .B f
32
+ Browse the highlighted commit's files
33
+ .TP
34
+ .B /
35
+ Filter the commit table (esc clears)
36
+ .TP
37
+ .B left / right
38
+ Previous / next language, or back / forward a week on the graph
39
+ .TP
40
+ .B h / l
41
+ Select the older / newer active day
42
+ .TP
43
+ .B [ / ]
44
+ Step through years
45
+ .TP
46
+ .B r
47
+ Cycle the date range
48
+ .TP
49
+ .B b
50
+ Pick a branch
51
+ .TP
52
+ .B ?
53
+ Show the key reference
54
+ .TP
55
+ .B q
56
+ Quit
57
+ .SS Commit detail
58
+ .TP
59
+ .B j / k or up / down
60
+ Move within the focused pane
61
+ .TP
62
+ .B tab / shift+tab
63
+ Switch between panes
64
+ .TP
65
+ .B [ / ]
66
+ Previous / next commit
67
+ .TP
68
+ .B p
69
+ Toggle file diff and full patch
70
+ .TP
71
+ .B f
72
+ Browse this commit's files
73
+ .TP
74
+ .B /
75
+ Filter the files list, or search the patch
76
+ .TP
77
+ .B enter / shift+enter
78
+ Next / previous patch match while searching
79
+ .TP
80
+ .B n / N
81
+ Next / previous patch match
82
+ .TP
83
+ .B left / right
84
+ Scroll the patch sideways when lines are not wrapped
85
+ .TP
86
+ .B page up / page down
87
+ Scroll by a page
88
+ .TP
89
+ .B home / end
90
+ Jump to the top or bottom
91
+ .TP
92
+ .B drag / ctrl+c
93
+ Select patch text with the mouse, then copy it
94
+ .TP
95
+ .B esc / q
96
+ Back (esc first closes the search)
97
+ .SS Branch picker
98
+ .TP
99
+ .B type
100
+ Filter the branch list
101
+ .TP
102
+ .B up / down
103
+ Move the highlight
104
+ .TP
105
+ .B enter
106
+ Switch to the highlighted branch
107
+ .TP
108
+ .B esc / q
109
+ Cancel
110
+ .SS Commit files
111
+ .TP
112
+ .B j / k or up / down
113
+ Move between files
114
+ .TP
115
+ .B /
116
+ Filter the list (esc clears)
117
+ .TP
118
+ .B [ / ]
119
+ Previous / next commit
120
+ .TP
121
+ .B enter
122
+ Open the highlighted file
123
+ .TP
124
+ .B esc / q
125
+ Back
126
+ .SS File view
127
+ .TP
128
+ .B j / k or up / down
129
+ Scroll (arrows scroll even while searching)
130
+ .TP
131
+ .B /
132
+ Search in the file
133
+ .TP
134
+ .B enter / shift+enter
135
+ Next / previous match while searching
136
+ .TP
137
+ .B n / N
138
+ Next / previous match
139
+ .TP
140
+ .B left / right
141
+ Scroll sideways when lines are not wrapped
142
+ .TP
143
+ .B [ / ]
144
+ Previous / next file
145
+ .TP
146
+ .B page up / page down
147
+ Scroll by a page
148
+ .TP
149
+ .B home / end
150
+ Jump to the top or bottom
151
+ .TP
152
+ .B drag / ctrl+c
153
+ Select text with the mouse, then copy it
154
+ .TP
155
+ .B esc / q
156
+ Back (esc first closes the search)
157
+ .SH FILES
158
+ .TP
159
+ .I ~/.config/vidi/config.json
160
+ Saved preferences (honors XDG_CONFIG_HOME).
161
+ .SH SEE ALSO
162
+ .BR git (1)
@@ -0,0 +1,162 @@
1
+ .TH VIDI 1 "" "vidi" "vidi manual"
2
+ .SH NAME
3
+ vidi, git\-view, git\-vidi \- browse a local git repository in the terminal
4
+ .SH SYNOPSIS
5
+ .B vidi [\-h] [\-\-version] [repo_dir]
6
+ .SH DESCRIPTION
7
+ Opens the repository you are in when given no path. Settings such as the theme and the language scan are changed inside the app from the command palette (Ctrl+P). The same program runs as vidi, git view and git vidi.
8
+ .SH OPTIONS
9
+ .TP
10
+ .B \-h, \-\-help
11
+ show this help message and exit
12
+ .TP
13
+ .B \-\-version
14
+ show program's version number and exit
15
+ .TP
16
+ .B repo_dir
17
+ Path inside a local git repository (defaults to the current folder)
18
+ .SH KEYS
19
+ Press ? in the app to show these keys.
20
+ .SS Main screen
21
+ .TP
22
+ .B j / k or up / down
23
+ Move within the focused panel
24
+ .TP
25
+ .B tab / shift+tab
26
+ Switch between panels
27
+ .TP
28
+ .B enter
29
+ Open the commit, or the highlighted language's files
30
+ .TP
31
+ .B f
32
+ Browse the highlighted commit's files
33
+ .TP
34
+ .B /
35
+ Filter the commit table (esc clears)
36
+ .TP
37
+ .B left / right
38
+ Previous / next language, or back / forward a week on the graph
39
+ .TP
40
+ .B h / l
41
+ Select the older / newer active day
42
+ .TP
43
+ .B [ / ]
44
+ Step through years
45
+ .TP
46
+ .B r
47
+ Cycle the date range
48
+ .TP
49
+ .B b
50
+ Pick a branch
51
+ .TP
52
+ .B ?
53
+ Show the key reference
54
+ .TP
55
+ .B q
56
+ Quit
57
+ .SS Commit detail
58
+ .TP
59
+ .B j / k or up / down
60
+ Move within the focused pane
61
+ .TP
62
+ .B tab / shift+tab
63
+ Switch between panes
64
+ .TP
65
+ .B [ / ]
66
+ Previous / next commit
67
+ .TP
68
+ .B p
69
+ Toggle file diff and full patch
70
+ .TP
71
+ .B f
72
+ Browse this commit's files
73
+ .TP
74
+ .B /
75
+ Filter the files list, or search the patch
76
+ .TP
77
+ .B enter / shift+enter
78
+ Next / previous patch match while searching
79
+ .TP
80
+ .B n / N
81
+ Next / previous patch match
82
+ .TP
83
+ .B left / right
84
+ Scroll the patch sideways when lines are not wrapped
85
+ .TP
86
+ .B page up / page down
87
+ Scroll by a page
88
+ .TP
89
+ .B home / end
90
+ Jump to the top or bottom
91
+ .TP
92
+ .B drag / ctrl+c
93
+ Select patch text with the mouse, then copy it
94
+ .TP
95
+ .B esc / q
96
+ Back (esc first closes the search)
97
+ .SS Branch picker
98
+ .TP
99
+ .B type
100
+ Filter the branch list
101
+ .TP
102
+ .B up / down
103
+ Move the highlight
104
+ .TP
105
+ .B enter
106
+ Switch to the highlighted branch
107
+ .TP
108
+ .B esc / q
109
+ Cancel
110
+ .SS Commit files
111
+ .TP
112
+ .B j / k or up / down
113
+ Move between files
114
+ .TP
115
+ .B /
116
+ Filter the list (esc clears)
117
+ .TP
118
+ .B [ / ]
119
+ Previous / next commit
120
+ .TP
121
+ .B enter
122
+ Open the highlighted file
123
+ .TP
124
+ .B esc / q
125
+ Back
126
+ .SS File view
127
+ .TP
128
+ .B j / k or up / down
129
+ Scroll (arrows scroll even while searching)
130
+ .TP
131
+ .B /
132
+ Search in the file
133
+ .TP
134
+ .B enter / shift+enter
135
+ Next / previous match while searching
136
+ .TP
137
+ .B n / N
138
+ Next / previous match
139
+ .TP
140
+ .B left / right
141
+ Scroll sideways when lines are not wrapped
142
+ .TP
143
+ .B [ / ]
144
+ Previous / next file
145
+ .TP
146
+ .B page up / page down
147
+ Scroll by a page
148
+ .TP
149
+ .B home / end
150
+ Jump to the top or bottom
151
+ .TP
152
+ .B drag / ctrl+c
153
+ Select text with the mouse, then copy it
154
+ .TP
155
+ .B esc / q
156
+ Back (esc first closes the search)
157
+ .SH FILES
158
+ .TP
159
+ .I ~/.config/vidi/config.json
160
+ Saved preferences (honors XDG_CONFIG_HOME).
161
+ .SH SEE ALSO
162
+ .BR git (1)
@@ -0,0 +1,215 @@
1
+ Metadata-Version: 2.4
2
+ Name: git-vidi
3
+ Version: 0.1.0
4
+ Summary: A read-only terminal viewer for a local Git repository.
5
+ Author-email: affaan-git <216245812+affaan-git@users.noreply.github.com>
6
+ License-Expression: GPL-3.0-or-later
7
+ Project-URL: Homepage, https://github.com/affaan-git/vidi
8
+ Project-URL: Repository, https://github.com/affaan-git/vidi
9
+ Project-URL: Issues, https://github.com/affaan-git/vidi/issues
10
+ Keywords: git,textual,tui,terminal,repository,viewer
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3 :: Only
17
+ Classifier: Topic :: Software Development :: Version Control :: Git
18
+ Classifier: Topic :: Utilities
19
+ Requires-Python: >=3.9
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ Requires-Dist: textual<9,>=6.2
23
+ Provides-Extra: test
24
+ Requires-Dist: pytest>=8; extra == "test"
25
+ Dynamic: license-file
26
+
27
+ # vidi
28
+
29
+ <p align="center">
30
+ <img src="https://raw.githubusercontent.com/affaan-git/vidi/main/.github/demo.gif"
31
+ alt="vidi browsing a repository">
32
+ </p>
33
+
34
+ <p align="center">A read-only terminal viewer for a local Git repository.</p>
35
+
36
+ ## Install
37
+
38
+ ```bash
39
+ pipx install git-vidi # or uv tool install git-vidi or pip install git-vidi
40
+ ```
41
+
42
+ > [!IMPORTANT]
43
+ > Requires Python 3.9+ and `git` 2.24+ on `PATH`.
44
+
45
+ ## Run
46
+
47
+ ```bash
48
+ git view /path/to/repo # or vidi /path/to/repo
49
+ ```
50
+
51
+ Or from anywhere inside a repo:
52
+
53
+ ```bash
54
+ git view # or vidi
55
+ ```
56
+
57
+ The same program also runs as `git vidi`.
58
+
59
+ > [!TIP]
60
+ > For shorter commands use `alias gv='git view'`.
61
+
62
+ ## Layout
63
+
64
+ ```text
65
+ +-----------------------------------+---------------------------+
66
+ | Contribution Activity | Commit Details |
67
+ | (year heatmap, one cell per day) | (author, message, files |
68
+ | | changed for the current |
69
+ +-----------------------------------+ commit) |
70
+ | Year Commits | |
71
+ | (commit table for the selected +---------------------------+
72
+ | branch, year and range) | Languages |
73
+ | | (percentage bar and per- |
74
+ | | language breakdown) |
75
+ +-----------------------------------+---------------------------+
76
+ ```
77
+
78
+ `Tab` moves between the commit table, details panel, languages panel, and
79
+ graph. Selecting a day on the graph or a row in the commit table updates the
80
+ details panel. The commit table filter matches on message, author, hash, and
81
+ date.
82
+
83
+ Press `Enter` on a commit to open its diff, then `[` and `]` to step to the
84
+ previous or next commit. The languages panel shows the languages in the
85
+ highlighted commit's tree. Press `Enter` on a language to list its files at
86
+ that commit and `Enter` on a file to read it.
87
+
88
+ Press `f` from any panel or from the commit detail to browse the whole tree.
89
+ Use `[` and `]` in the file list to step between commits. Files changed in
90
+ the commit are marked with a dot. The branch picker shows how many commits each
91
+ branch is ahead of or behind the default branch (derived from `origin/HEAD` or
92
+ `main`/`master`).
93
+
94
+ ## Keys
95
+
96
+ Press `?` in the app for the same reference.
97
+
98
+ <details>
99
+ <summary>Click to expand</summary>
100
+
101
+ <!-- keys:start -->
102
+
103
+ ### Main screen
104
+
105
+ | Key | Action |
106
+ | --- | --- |
107
+ | `j` / `k` or `up` / `down` | Move within the focused panel |
108
+ | `tab` / `shift+tab` | Switch between panels |
109
+ | `enter` | Open the commit, or the highlighted language's files |
110
+ | `f` | Browse the highlighted commit's files |
111
+ | `/` | Filter the commit table (esc clears) |
112
+ | `left` / `right` | Previous / next language, or back / forward a week on the graph |
113
+ | `h` / `l` | Select the older / newer active day |
114
+ | `[` / `]` | Step through years |
115
+ | `r` | Cycle the date range |
116
+ | `b` | Pick a branch |
117
+ | `?` | Show the key reference |
118
+ | `q` | Quit |
119
+
120
+ ### Commit detail
121
+
122
+ | Key | Action |
123
+ | --- | --- |
124
+ | `j` / `k` or `up` / `down` | Move within the focused pane |
125
+ | `tab` / `shift+tab` | Switch between panes |
126
+ | `[` / `]` | Previous / next commit |
127
+ | `p` | Toggle file diff and full patch |
128
+ | `f` | Browse this commit's files |
129
+ | `/` | Filter the files list, or search the patch |
130
+ | `enter` / `shift+enter` | Next / previous patch match while searching |
131
+ | `n` / `N` | Next / previous patch match |
132
+ | `left` / `right` | Scroll the patch sideways when lines are not wrapped |
133
+ | `page up` / `page down` | Scroll by a page |
134
+ | `home` / `end` | Jump to the top or bottom |
135
+ | drag / `ctrl+c` | Select patch text with the mouse, then copy it |
136
+ | `esc` / `q` | Back (esc first closes the search) |
137
+
138
+ ### Branch picker
139
+
140
+ | Key | Action |
141
+ | --- | --- |
142
+ | type | Filter the branch list |
143
+ | `up` / `down` | Move the highlight |
144
+ | `enter` | Switch to the highlighted branch |
145
+ | `esc` / `q` | Cancel |
146
+
147
+ ### Commit files
148
+
149
+ | Key | Action |
150
+ | --- | --- |
151
+ | `j` / `k` or `up` / `down` | Move between files |
152
+ | `/` | Filter the list (esc clears) |
153
+ | `[` / `]` | Previous / next commit |
154
+ | `enter` | Open the highlighted file |
155
+ | `esc` / `q` | Back |
156
+
157
+ ### File view
158
+
159
+ | Key | Action |
160
+ | --- | --- |
161
+ | `j` / `k` or `up` / `down` | Scroll (arrows scroll even while searching) |
162
+ | `/` | Search in the file |
163
+ | `enter` / `shift+enter` | Next / previous match while searching |
164
+ | `n` / `N` | Next / previous match |
165
+ | `left` / `right` | Scroll sideways when lines are not wrapped |
166
+ | `[` / `]` | Previous / next file |
167
+ | `page up` / `page down` | Scroll by a page |
168
+ | `home` / `end` | Jump to the top or bottom |
169
+ | drag / `ctrl+c` | Select text with the mouse, then copy it |
170
+ | `esc` / `q` | Back (esc first closes the search) |
171
+
172
+ <!-- keys:end -->
173
+
174
+ </details>
175
+
176
+ ## Settings
177
+
178
+ Apart from the path, everything is set inside the app from the command palette
179
+ (`Ctrl+P`). Settings are saved to `~/.config/vidi/config.json`
180
+ (`%APPDATA%\vidi\config.json` on Windows) by default or
181
+ `$XDG_CONFIG_HOME/vidi/config.json` when set.
182
+
183
+ The command palette additionally exposes these settings:
184
+
185
+ - "Transparent background" uses the terminal's background and keeps the
186
+ theme's borders, selection, and text.
187
+ - "Graph: commit table follows on Enter" makes moving over the graph wait for
188
+ `Enter` before it selects a commit. "Graph: commit table follows as you move"
189
+ switches back to the default.
190
+ - "Language settings" chooses whether languages are measured by bytes or file
191
+ count, which languages to exclude, and which extra directories the scan skips.
192
+ - "Change theme" picks a theme. "Reset theme to default" switches back to the default.
193
+ - "Wrap lines in diffs" and "Wrap lines in file view" choose whether long lines
194
+ wrap or scroll sideways. Diffs wrap by default.
195
+
196
+ ## Development
197
+
198
+ ```bash
199
+ pip install -e ".[test]"
200
+ python -m pytest -q
201
+ ```
202
+
203
+ > [!IMPORTANT]
204
+ > The man pages in `man/` and the key tables in this README are generated from
205
+ > the `vidi -h` parser and the in-app help.
206
+ > **Regenerate with `python -m vidi.docs` after changing either.**
207
+ > A test will fail when they are out of date. Editable installs don't include
208
+ > the man pages, which `git view --help` opens on macOS and Linux. On Windows
209
+ > the keys are in `vidi -h` and `?`.
210
+
211
+ ## License
212
+
213
+ vidi is free software under the GNU General Public License v3.0 or later. See
214
+ [LICENSE](https://github.com/affaan-git/vidi/blob/main/LICENSE) for the full
215
+ text.