https://github.com/stiliajohny/historikeeper
A ZSH plugin that captures history in a database
https://github.com/stiliajohny/historikeeper
Last synced: 3 months ago
JSON representation
A ZSH plugin that captures history in a database
- Host: GitHub
- URL: https://github.com/stiliajohny/historikeeper
- Owner: stiliajohny
- License: gpl-3.0
- Created: 2024-07-25T16:59:46.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2024-11-20T16:32:45.000Z (about 1 year ago)
- Last Synced: 2024-11-20T17:34:07.849Z (about 1 year ago)
- Language: Shell
- Size: 547 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
- awesome-zsh-plugins - historikeeper - Captures history in a database. (Plugins / ZSH on Windows)
- fucking-awesome-zsh-plugins - historikeeper - Captures history in a database. (Plugins / ZSH on Windows)
README
[![Contributors][contributors-shield]][contributors-url]
[![Forks][forks-shield]][forks-url]
[![Stargazers][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[![GPL3 License][license-shield]][license-url]
[![LinkedIn][linkedin-shield]][linkedin-url]
[![Ask Me Anything][ask-me-anything]][personal-page]
historikeeper
A ZSH plugin that captures history in a database
Explore the docs »
Report Bug
·
Request Feature
## Table of Contents
- [Table of Contents](#table-of-contents)
- [About The Project](#about-the-project)
- [Built With](#built-with)
- [Getting Started](#getting-started)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Usage](#usage)
- [Roadmap](#roadmap)
- [Contributing](#contributing)
- [License](#license)
- [Contact](#contact)
- [Acknowledgements](#acknowledgements)
## About The Project
### Built With
- [Zsh](https://www.zsh.org)
- [PostgreSQL](https://www.postgresql.org)
- [SQLite](https://www.sqlite.org)
- [Docker](https://www.docker.com)
- [Python](https://www.python.org)
---
## Getting Started
### Prerequisites
- Docker
- PostgreSQL client (optional, for manual access to the database)
- SQLite (optional, for local file-based logging)
- Python 3.6+
- `pip` (Python package installer)
### Installation
1. **Clone the repo**
```sh
git clone https://github.com/stiliajohny/historikeeper.git \$ZSH_CUSTOM/plugins/historikeeper
```
2. **Deploy PostgreSQL with Docker (optional if using PostgreSQL)**
```sh
docker pull postgres
docker run --name postgres-db -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=mysecretpassword -e POSTGRES_DB=historykeeper -p 5432:5432 -d postgres
```
3. **Install Python dependencies**
```sh
pip install -r \$ZSH_CUSTOM/plugins/historikeeper/requirements.txt
```
4. **Add the plugin to your .zshrc configuration**
```sh
plugins=(... historikeeper)
```
5. **Set variables in your .zshrc**
```sh
HISTORIKEEPER_PRINT_DETAILS=true
HISTORIKEEPER_LOG_METHOD="postgres" # Options: "postgres" or "sqlite"
# if postgress is used then set the following variables
PG_HOST=localhost
PG_PORT=5432
PG_USER=postgres
PG_DB=historykeeper
PG_PASSWORD=mysecretpassword
# if sqlite is used then set the following variables
SQLITE_DB_PATH=~/.zsh_history.db
```
6. **Source your .zshrc to apply the changes**
```sh
source ~/.zshrc
```
---
## Usage
### Import existing history
1. CD in the plugin folder
```bash
cd \$ZSH_CUSTOM/plugins/historikeeper/
```
2. Run the import command
```bash
python3 ./parse_zsh_history.py -vvvv --input-file ~/.zsh_history --pg-host localhost --pg-port 5432 --pg-user postgres --pg-password mysecretpassword --pg-db historykeeper
```
### Normal Plugin Usage
The plugin captures each command run in your terminal and logs it to the specified database method (PostgreSQL or SQLite) based on the value of `HISTORIKEEPER_LOG_METHOD`.
You can view the details of the last command executed directly in your terminal if `HISTORIKEEPER_PRINT_DETAILS` is set to `true`.
Example of what is captured:
```shell
johnstilia in ~/.config/oh-my-zsh/custom/plugins/historikeeper on master ● ● λ ls
HistoriKeeper.plugin.zsh LICENSE.txt README.md _config.yml
>--------------------------------------------------
Last Command Details:
Epoch Timestamp: 1721927239
Timestamp: 2024-07-25T18:07:19+0100
Command: ls
Command Arguments:
Exit Code: 0
Execution Time (milliseconds): 12
Hostname: Johns-MacBook-Pro.local
Username: johnstilia
Output:
HistoriKeeper.plugin.zsh
LICENSE.txt
README.md
_config.yml
IP Address: Johns-MacBook-Pro.local
PPID: 58531
TTY: /dev/ttys055
Working Directory: /Users/johnstilia/.config/oh-my-zsh/custom/plugins/historikeeper
Shell Type: /bin/zsh
Session Start Time: 2024-07-25T18:07:17+0100
Public IP Address: 152.37.89.249
Public Hostname: 89.37.152.249.bcube.co.uk
>--------------------------------------------------
Toggling Variables:
HISTORIKEEPER_PRINT_DETAILS: true
HISTORIKEEPER_LOG_METHOD: postgres
>--------------------------------------------------
```
---
## Roadmap
See the [open issues](https://github.com/stiliajohny/historikeeper/issues) for a list of proposed features (and known issues).
---
## Contributing
Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are **greatly appreciated**.
1. Fork the Project
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the Branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
---
## License
Distributed under the GPLv3 License. See `LICENSE` for more information.
## Contact
John Stilia - stilia.johny@gmail.com
---
## Acknowledgements
- [GitHub Emoji Cheat Sheet](https://www.webpagefx.com/tools/emoji-cheat-sheet)
- [Img Shields](https://shields.io)
- [Choose an Open Source License](https://choosealicense.com)
- [GitHub Pages](https://pages.github.com)
[contributors-shield]: https://img.shields.io/github/contributors/stiliajohny/historikeeper.svg?style=for-the-badge
[contributors-url]: https://github.com/stiliajohny/historikeeper/graphs/contributors
[forks-shield]: https://img.shields.io/github/forks/stiliajohny/historikeeper.svg?style=for-the-badge
[forks-url]: https://github.com/stiliajohny/historikeeper/network/members
[stars-shield]: https://img.shields.io/github/stars/stiliajohny/historikeeper.svg?style=for-the-badge
[stars-url]: https://github.com/stiliajohny/historikeeper/stargazers
[issues-shield]: https://img.shields.io/github/issues/stiliajohny/historikeeper.svg?style=for-the-badge
[issues-url]: https://github.com/stiliajohny/historikeeper/issues
[license-shield]: https://img.shields.io/github/license/stiliajohny/historikeeper?style=for-the-badge
[license-url]: https://github.com/stiliajohny/historikeeper/blob/master/LICENSE.txt
[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555
[linkedin-url]: https://linkedin.com/in/john.stilia/
[product-screenshot]: .assets/screenshot.png
[ask-me-anything]: https://img.shields.io/badge/Ask%20me-anything-1abc9c.svg?style=for-the-badge
[personal-page]: https://github.com/stiliajohny