ghostnotes 1.0.0__py3-none-any.whl

ghostnotes/cli.py

@@ -0,0 +1,54 @@
+# CLI setup
+import argparse
+from ghostnotes.hook import install_hook, strip_ghostnotes
+from ghostnotes.config import create_config, update_exclude, set_tag, add_lang_support
+from ghostnotes.sync import pull, extract_notes
+
+def main():
+    parser = argparse.ArgumentParser(description="GhostNotes")
+    subparsers = parser.add_subparsers(dest="command")
+
+    # init
+    init_parser = subparsers.add_parser("init", help="Initialize GhostNotes")
+
+    # set tag
+    tag_parser = subparsers.add_parser("set-tag", help="Set the tag for GhostNotes to ignore, Default tag is 'GN:'. ")
+    tag_parser.add_argument("--tag", required=True, help="New tag")
+
+    # add lang
+    lang_parser = subparsers.add_parser("add-lang", help="Add a new language support, Check .ghostnotes for the default languages supported")
+    lang_parser.add_argument("--ext", required=True, help="File extension (.py, .js, .sql etc.)")
+    lang_parser.add_argument("--symb", required=True, help="Symbol for commenting in the said language (# for .py, // for .java etc.)")
+
+    # pull
+    pull_parser = subparsers.add_parser("pull", help="Git pull with ghostnote-safe stripping and re-applying")
+
+    # status
+    status_parser = subparsers.add_parser("status", help="Show all ghost notes in the project")
+
+    args = parser.parse_args()
+
+    if args.command == "init":
+        create_config()
+        update_exclude()
+        install_hook()
+        print("GhostNotes is successfully initialized.")
+    elif args.command == "set-tag":
+        set_tag(args.tag)
+    elif args.command == "add-lang":
+        add_lang_support(args.ext, args.symb)
+    elif args.command == "pull":
+        pull()
+    elif args.command == "status":
+        notes = extract_notes()
+        if not notes:
+            print("No ghost notes found.")
+        else:
+            total = sum(len(v) for v in notes.values())
+            print(f"Found {total} ghost note(s):\n")
+            for file, file_notes in notes.items():
+                for n in file_notes:
+                    print(f"  {file}:{n['line_number'] + 1}  — {n['note']}")
+
+if __name__ == "__main__":
+    main()

ghostnotes/config.py

@@ -0,0 +1,74 @@
+# file for creating the .ghostnotes configuration
+import configparser
+import os
+
+def create_config():
+    if not os.path.isdir('.git'):
+        print("This project is not initialized with git. GhostNotes only works for directories already initialized with git.")
+        return
+
+    else:
+        # set-up the default config
+        config = configparser.ConfigParser()
+        config['settings'] = {'tag': 'GN:'}
+        config['languages'] = {'.py': '#', '.java': '//', '.js': '//', '.ts': '//'}
+
+        with open('.ghostnotes', 'w') as configfile:
+            config.write(configfile)
+
+        print("GhostNotes: Config file is created succesfully")
+
+def update_exclude():
+    loc = ".git/info/exclude"
+    
+    with open(loc, 'r') as file:
+        for line in file:
+            # already in exclude
+            if line.strip() == '.ghostnotes':
+                return
+            
+    file = open(loc, "a")
+    file.write('.ghostnotes\n')
+    file.close()
+        
+def load_config():
+    # check if config exists
+    if not os.path.isfile('.ghostnotes'):
+        print("This project is not initialized with GhostNotes.")
+        return
+    
+    else:
+        # set-up the default config
+        config = configparser.ConfigParser()
+        config.read('.ghostnotes')
+        print("GhostNotes: Config file is read succesfully")
+
+        return config
+
+# update tag 
+def set_tag(tag):
+    if not os.path.isfile('.ghostnotes'):
+        print("This project is not initialized with GhostNotes, cannot set new tag.")
+        return
+    
+    config = configparser.ConfigParser()
+    config.read('.ghostnotes')          # preserve existing settings
+    config['settings']['tag'] = tag
+    with open('.ghostnotes', 'w') as configfile:
+        config.write(configfile)
+
+    print(f"GhostNotes: Config file tag is set to {tag} succesfully")
+
+# add custom language comment support
+def add_lang_support(extension, notation):
+    if not os.path.isfile('.ghostnotes'):
+        print("This project is not initialized with GhostNotes, cannot add new file support.")
+        return
+    
+    config = configparser.ConfigParser()
+    config.read('.ghostnotes')
+    config['languages'][extension] = notation
+    with open('.ghostnotes', 'w') as configfile:
+        config.write(configfile)
+
+    print(f"GhostNotes: Config file language support for {extension} files are added with symbol {notation} successfuly.")

ghostnotes/hook.py

@@ -0,0 +1,103 @@
+import os
+import stat
+import subprocess
+from pathlib import Path 
+from ghostnotes.config import load_config
+
+# for adding this script to pre-commit
+def install_hook():
+    path = '.git/hooks/pre-commit'
+    command = 'python3 -m ghostnotes.hook'
+
+    # if a pre-commit hook file already exists:
+    if os.path.exists(path):
+        with open(path, 'r') as file:
+            for line in file:
+                if line.strip() == command:
+                    return
+            
+        with open(path, 'a') as file:
+            file.write(f'\n{command}\n')
+    else:
+        with open(path, 'w') as file:
+            file.write(f'#!/bin/bash\n{command}\n')
+
+    # make the file executable
+    os.chmod(path, os.stat(path).st_mode | stat.S_IEXEC)
+
+# main logic function for stripping the committed files of the keyworded comments
+def strip_ghostnotes():
+    """
+    Read Config
+    Get the list of staged files — how do you ask git which files are staged? Think about what terminal command you'd run manually.
+    Filter to only supported extensions
+    For each supported file, strip lines matching the tag.
+    Re-stage the files with git add
+    """
+    # read config
+    configuration = load_config()
+
+    if configuration is None:
+        print("Ghostnotes is not configured.")
+        return
+
+    # get the list of staged file:
+    res = subprocess.run(['git', 'diff', '--name-only', '--cached'], capture_output=True, text=True)
+    staged_files = res.stdout.splitlines()
+    supported_staged_files = list()
+
+    # filter staged_files to only supported file types
+    for f in staged_files:
+        if Path(f).suffix in configuration['languages']:
+            supported_staged_files.append(f)
+
+    # strip lines matching the tag
+    for file in supported_staged_files:
+        # check the commenting style for the file type from configuration['languages'] as well as the tag from configuration['settings'] to build the exact sequence of chars we are looking for
+        comment = configuration['languages'][Path(file).suffix]
+        tag = configuration['settings']['tag']
+        pattern = comment + ' ' + tag
+
+        # read the staged version from the git index, not the working tree
+        staged_content = subprocess.run(
+            ['git', 'show', f':{file}'],
+            capture_output=True, text=True
+        ).stdout
+
+        new_lines = list()
+        for line in staged_content.splitlines(keepends=True):
+            # strip only if the pattern is not inside a string literal
+            if pattern in line:
+                idx = line.index(pattern)
+                prefix = line[:idx]
+                # if an odd number of quotes precede the pattern, it's inside a string
+                in_string = (prefix.count('"') % 2 == 1) or (prefix.count("'") % 2 == 1)
+                if not in_string:
+                    line = line[:idx].rstrip() + '\n'
+            new_lines.append(line)
+
+        stripped_content = ''.join(new_lines)
+
+        # write the stripped content back into the git index only
+        hash_result = subprocess.run(
+            ['git', 'hash-object', '-w', '--stdin'],
+            input=stripped_content, capture_output=True, text=True
+        )
+        blob_hash = hash_result.stdout.strip()
+
+        # get the file's mode from the index
+        ls_result = subprocess.run(
+            ['git', 'ls-files', '--stage', file],
+            capture_output=True, text=True
+        )
+        if not ls_result.stdout.strip():
+            continue
+        mode = ls_result.stdout.split()[0]
+
+        # update the index entry with the new blob
+        subprocess.run(
+            ['git', 'update-index', '--cacheinfo', f'{mode},{blob_hash},{file}']
+        )
+
+if __name__ == "__main__":
+    strip_ghostnotes()

ghostnotes/sync.py

@@ -0,0 +1,140 @@
+import subprocess
+from pathlib import Path
+from ghostnotes.config import load_config
+
+
+def extract_notes():
+    config = load_config()
+    notes = {}
+
+    for file in Path('.').rglob('*'):
+        # skip hidden directories (.git, .venv, etc.)
+        if any(part.startswith('.') for part in file.parts):
+            continue
+
+        if not file.is_file():
+            continue
+
+        ext = file.suffix
+        if ext not in config['languages']:
+            continue
+
+        comment = config['languages'][ext]
+        tag = config['settings']['tag']
+        pattern = comment + ' ' + tag
+
+        # extract notes, store code without comment, store comment, and store line num
+        file_notes = []
+        try:
+            with open(file, 'r') as f:
+                for i, line in enumerate(f):
+                    if pattern in line:
+                        stripped = line.split(pattern)[0].rstrip()
+                        note_text = line.split(pattern, 1)[1].strip()
+                        file_notes.append({
+                            'stripped_line': stripped,
+                            'note': note_text,
+                            'line_number': i,
+                        })
+        except UnicodeDecodeError:
+            continue
+
+        if file_notes:
+            notes[str(file)] = file_notes
+
+    return notes
+
+def strip_working_tree(notes):
+    for file, file_notes in notes.items():
+        patterns = {n['line_number'] for n in file_notes}
+
+        with open(file, 'r') as f:
+            lines = f.readlines()
+
+        for line_num in patterns:
+            note_entry = next(n for n in file_notes if n['line_number'] == line_num)
+            lines[line_num] = note_entry['stripped_line'] + '\n'
+
+        with open(file, 'w') as f:
+            f.writelines(lines)
+
+
+def reapply_notes(notes, config):
+    for file, file_notes in notes.items():
+        if not Path(file).is_file():
+            for n in file_notes:
+                print(f"  ORPHANED (file deleted): {file} — {n['note']}")
+            continue
+
+        comment = config['languages'][Path(file).suffix]
+        tag = config['settings']['tag']
+        pattern = comment + ' ' + tag
+
+        with open(file, 'r') as f:
+            lines = f.readlines()
+
+        orphaned = []
+
+        for n in file_notes:
+            target = n['stripped_line']
+            line_num = n['line_number']
+            matched = False
+
+            # 1. exact match at same line number
+            if line_num < len(lines) and lines[line_num].rstrip() == target:
+                lines[line_num] = target + ' ' + pattern + ' ' + n['note'] + '\n'
+                matched = True
+
+            # 2. exact match nearby (within 20 lines)
+            if not matched:
+                start = max(0, line_num - 20)
+                end = min(len(lines), line_num + 20)
+                for i in range(start, end):
+                    if lines[i].rstrip() == target:
+                        lines[i] = target + ' ' + pattern + ' ' + n['note'] + '\n'
+                        matched = True
+                        break
+
+            # 3. exact match anywhere in file
+            if not matched:
+                for i in range(len(lines)):
+                    if lines[i].rstrip() == target:
+                        lines[i] = target + ' ' + pattern + ' ' + n['note'] + '\n'
+                        matched = True
+                        break
+
+            # 4. orphaned
+            if not matched:
+                orphaned.append(n)
+
+        with open(file, 'w') as f:
+            f.writelines(lines)
+
+        for n in orphaned:
+            print(f"  ORPHANED: {file}:{n['line_number']} — {n['note']}")
+
+
+def pull():
+    config = load_config()
+    notes = extract_notes()
+
+    if notes:
+        print(f"GhostNotes: Saved {sum(len(v) for v in notes.values())} note(s), stripping before pull...")
+        strip_working_tree(notes)
+
+    result = subprocess.run(['git', 'pull'], capture_output=True, text=True)
+    print(result.stdout)
+    if result.stderr:
+        print(result.stderr)
+
+    if notes:
+        if result.returncode != 0:
+            print("GhostNotes: Pull failed, restoring notes to working tree...")
+            reapply_notes(notes, config)
+            print("GhostNotes: Notes restored. Resolve the pull issue and try again.")
+        else:
+            print("GhostNotes: Re-applying notes...")
+            reapply_notes(notes, config)
+            print("GhostNotes: Done.")
+
+    return result.returncode

ghostnotes-1.0.0.dist-info/METADATA

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: ghostnotes
+Version: 1.0.0
+Summary: Strip personal annotations from code before committing
+Author-email: Tuna Akin <tuna.takin@gmail.com>
+License-Expression: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# GhostNotes
+**Version:** 1.0.0 | **Last Updated:** April 12, 2026
+
+A Git tool that strips tagged comments before committing.
+
+---
+
+## Installation
+
+```bash
+pip install ghostnotes
+```
+
+Then initialize in any git repo:
+
+```bash
+cd your-project
+ghostnotes init
+```
+
+---
+
+## What it does
+GhostNotes lets you leave personal notes in your code using a tag (default: `GN:`). Before every commit, it automatically strips them out so they never reach your repository.
+```python
+x = some_function() # GN: this breaks when input is negative, fix later
+```
+This comment line gets stripped before the commit so it looks like:
+```python
+x = some_function()
+```
+
+Your local file stays untouched.
+
+---
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `ghostnotes init` | Initialize GhostNotes in the current project |
+| `ghostnotes status` | Show all GhostNotes in the current project |
+| `ghostnotes set-tag --tag <tag>` | Change the default comment tag |
+| `ghostnotes add-lang --ext <.ext> --symb <symbol>` | Add support for a new language |
+| `ghostnotes pull` | Git pull that safely strips and re-applies your ghostnotes |

ghostnotes-1.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+ghostnotes/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ghostnotes/cli.py,sha256=mSpnu9y1oLkShcbH6Z1IEh0XAr6n3nC6CQ1KS82LvGQ,2116
+ghostnotes/config.py,sha256=CYBoSVkcTn_-IZQuhjlY4HqqIRLrvNlr2_nLl637bRk,2398
+ghostnotes/hook.py,sha256=PnhyxuAZJXXG_uJRl7A59K6yAQHan7dWgmkhgyoZ7-E,3740
+ghostnotes/sync.py,sha256=WpAdVJmH5d-xHS7Luov-mijwByS3I_OaFq3qXvRKptE,4477
+ghostnotes-1.0.0.dist-info/licenses/LICENSE,sha256=nOQImqRAvHs2zvX_672bmFNV8j1E34KEVWXKMLc_YB8,1066
+ghostnotes-1.0.0.dist-info/METADATA,sha256=oKOtOzVMYZhiJkq0-Eu9cVwoi-wuSX92C9gsH9SKt5E,1413
+ghostnotes-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+ghostnotes-1.0.0.dist-info/entry_points.txt,sha256=ePr6r5ZXsebGdIkj_q_hcD8_qkWkiir-PTYCdfHBolc,51
+ghostnotes-1.0.0.dist-info/top_level.txt,sha256=KgbY9qlqn3rtYmhkjV4cnWFn1qReukDtWfyUh8Tbzxg,11
+ghostnotes-1.0.0.dist-info/RECORD,,

ghostnotes-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ghostnotes-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ghostnotes = ghostnotes.cli:main

ghostnotes-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tuna Akin
+
+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.

ghostnotes-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ghostnotes