fsync 1.0.0__tar.gz

fsync-1.0.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: fsync
+Version: 1.0.0
+Summary: Local file synchronization for scattered shared libraries
+Author: Xaeian
+License: MIT
+Project-URL: Repository, https://github.com/Xaeian/FSync
+Keywords: sync,files,libraries,backup
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: xaeian
+Provides-Extra: diff
+Requires-Dist: rich; extra == "diff"
+Provides-Extra: all
+Requires-Dist: rich; extra == "all"
+
+## 📖 FSync
+
+This tool **eliminates the problem of scattered libraries** by synchronizing 🔄 selected files spread across different projects on your machine _(locally)_. No more chaos and manual file copying.
+
+At first glance, centralizing libraries seems like a great idea. It makes work easier and avoids code duplication. In practice, however, some complications arise:
+
+- You don't always want to update a library in a project you're no longer developing, but it still needs to work.
+- Some libraries must be part of the repository. When you hand off/close a project, you want everything in one place, without having to pull additional dependencies from external sources.
+- It's better when all resources are in the project directory. It simplifies configuration _(Makefile, CMake)_, eliminates path and version issues, and improves IDE integration.
+
+This solution is perfect if you run many smaller projects and care about efficient library management _(code that appears across multiple projects)_. If you make frequent changes, want to avoid messy code, but don't have time to spend hours organizing dependencies: this tool is for you! The program is dead simple. What matters is efficient and effective work, without unnecessary bureaucracy. The open source community can do its thing, but here the priority is a happy client and a working project done ⚡**fast** and 👍**good enough**.
+
+### 🧐 Problems!
+
+- ❌ **Possible accidental overwrites**: if you edit two versions of a library at the same time.
+- ✅ Avoid this, but if it happens, every overwritten version is saved as a timestamped backup, so you can always recover your changes.
+- ❌ **No environment isolation**: different projects may require different versions of the same library.
+- ✅ Not a problem! Just create separate entries for different versions, keeping synchronization independent. You can also comment out entries for libraries that shouldn't be updated anymore.
+- ❌ **Code duplication across repositories**: instead of one library copy, you have several in different projects.
+- ✅ That's the point! Each client should have their own library version, with no dependencies on other repos. Full control, zero unnecessary complications.
+
+### 🤔 Alternatives?
+
+Of course you can approach this more professionally by:
+
+- Versioning libraries as separate projects/repositories and updating them as needed.
+- Using Git **Submodules**, which allows tracking library versions in the repository.
+- External package managers _(`pip`, `npm`, `cargo`)_ that simplify dependency management.
+
+If any of our libraries reach a stable version that we don't chaotically change every project, and they're good enough, it's worth considering one of the above solutions.
+
+### ⚙️ Config
+
+The **`sync.json`** file defines file synchronization configuration. Each entry is a key _(filename)_ and a list of paths to synchronize. Keys starting with `#` are treated as commented out and skipped.
+
+Paths can use shorthand notation via the **`dict.ini`** file, which defines aliases for frequently repeated locations. In `sync.json` paths you can reference these aliases using `{key}` notation.
+
+#### Example
+
+Running the program with the `-e`, `--example` flag will create example config files locally.
+
+File `dict.ini`
+
+```ini
+web = C:/Users/Me/Projects/WebPage/backend
+staff = C:/Users/Me/Desktop/MyStaff/test
+work = C:/Users/Me/Work/Drivers/repos
+```
+
+File `sync.json`
+
+```json
+{
+  "serial.c": ["{staff}/serial.c", "{work}/PLC/serial_port.c"],
+  "utils.py": ["{web}/lib/utils.py", "{work}/PLC/misc.py"],
+  "#old_lib.c": ["{staff}/old_lib.c", "{work}/legacy/old_lib.c"]
+}
+```
+
+### 📦 Install
+
+```sh
+pip install fsync        # basic
+pip install fsync[diff]  # + rich (diff display)
+```
+
+> Also available as standalone `.exe` on [GitHub Releases](https://github.com/Xaeian/FSync/releases).
+
+### 🚀 Use
+
+First, set the workspace: the directory containing your config files (`sync.json`, `dict.ini`) and where backups will be stored:
+
+```sh
+fsync -w C:/Projects/sync  # specified path
+fsync -w                   # current directory
+```
+
+Running the program generates a report:
+
+```bash
+fsync
+```
+
+To synchronize _(i.e. update older file versions)_, just add the `-u`, `--update` flag:
+
+```bash
+fsync -u
+```
+
+For each pair of files with discrepancies, tags are generated. You can use them to inspect differences between files with the `-d`, `--diff` flag:
+
+```bash
+fsync -d 1.1
+```

fsync-1.0.0/fsync/__init__.py

@@ -0,0 +1,31 @@
+# fsync/__init__.py
+
+"""
+FSync: local file synchronization tool.
+
+Keeps scattered copies of shared libraries in sync across projects.
+Works as CLI (`py -m fsync`), pip-installed command (`fsync`),
+or importable module.
+
+Example:
+  >>> from fsync.main import main
+  >>> from fsync.utils import backup_file
+  >>> from fsync.diff import show
+"""
+
+__version__ = "1.0.0"
+__repo__ = "Xaeian/FSync"
+__python__ = ">=3.12"
+__description__ = "Local file synchronization for scattered shared libraries"
+__author__ = "Xaeian"
+__keywords__ = ["sync", "files", "libraries", "backup"]
+__dependencies__ = ["xaeian"]
+__scripts__ = {
+  "fsync": "fsync.__main__:main",
+}
+
+from .utils import backup_file, BACKUP_DIR, BACKUP_KEEP
+
+__all__ = [
+  "backup_file", "BACKUP_DIR", "BACKUP_KEEP",
+]

fsync-1.0.0/fsync/__main__.py

@@ -0,0 +1,4 @@
+# fsync/__main__.py
+
+from .main import main
+main()

fsync-1.0.0/fsync/args.py

@@ -0,0 +1,19 @@
+# fsync/args.py
+
+import argparse
+
+def load_args():
+  parser = argparse.ArgumentParser(description="FSync: File synchronization tool")
+  parser.add_argument("-w", "--workspace", type=str, nargs="?", const=".", default=None,
+    help="Set workspace directory (default: current dir)")
+  parser.add_argument("-u", "--update", action="store_true",
+    help="Update files to latest version (most recently modified)")
+  parser.add_argument("-i", "--info", action="store_true",
+    help="Display all synchronized files")
+  parser.add_argument("-e", "--example", action="store_true",
+    help="Create example config files")
+  parser.add_argument("-d", "--diff", type=str, nargs="?",
+    help="Compare files by tag: <latest>.<obsolete>", default="")
+  parser.add_argument("-v", "--version", action="store_true",
+    help="Program version and repository")
+  return parser.parse_args()

fsync-1.0.0/fsync/diff.py

@@ -0,0 +1,32 @@
+# fsync/diff.py
+
+__extras__ = ("diff", ["rich"])
+
+import sys, difflib
+from xaeian import FILE, PATH, Print, Color as c, replace_map
+
+def show(file_a:str, file_b:str, mapping:dict|None=None):
+  try:
+    from rich.console import Console
+    from rich.syntax import Syntax
+  except ImportError:
+    p = Print()
+    p.err(f"Missing {c.TURQUS}rich{c.END} package for diff display")
+    p.run(f"Install: {c.YELLOW}pip{c.END} install fsync[diff]")
+    sys.exit(1)
+  lines_a = FILE.load_lines(file_a)
+  lines_b = FILE.load_lines(file_b)
+  if mapping:
+    label_a = replace_map(PATH.normalize(file_a), mapping)
+    label_b = replace_map(PATH.normalize(file_b), mapping)
+  else:
+    label_a, label_b = file_a, file_b
+  result = "".join(difflib.unified_diff(
+    lines_a, lines_b,
+    fromfile=label_a, tofile=label_b,
+  ))
+  if result:
+    Console().print(Syntax(
+      result, "diff", theme="ansi_dark",
+      line_numbers=True, background_color=None,
+    ))

fsync-1.0.0/fsync/example.py

@@ -0,0 +1,30 @@
+# fsync/example.py
+
+"""Generate example config files (dict.ini, sync.json)."""
+
+import os, platform
+from xaeian import JSON, INI, FILE, Print, Color as c
+
+def create():
+  p = Print()
+  user = os.getlogin()
+  if platform.system() == "Windows": base = f"C:/Users/{user}"
+  else: base = f"/home/{user}"
+  mydict = {
+    "web": f"{base}/Projects/WebPage/backend",
+    "staff": f"{base}/Desktop/MyStaff/test",
+    "work": f"{base}/Work/Drivers/repos",
+  }
+  sync = {
+    "serial.c": ["{staff}/serial.c", "{work}/PLC/serial_port.c"],
+    "utils.py": ["{web}/lib/utils.py", "{work}/PLC/misc.py"],
+  }
+  for name, data, saver in [
+    ("dict.ini", mydict, INI.save),
+    ("sync.json", sync, JSON.save_pretty),
+  ]:
+    if FILE.exists(name):
+      p.err(f"File {c.RED}{name}{c.END} already exists. Delete it to generate example")
+    else:
+      saver(name, data)
+      p.ok(f"Template {c.GREEN}{name}{c.END} generated")

fsync-1.0.0/fsync/main.py

@@ -0,0 +1,175 @@
+# fsync/main.py
+
+"""
+FSync: file synchronization engine.
+
+Core sync logic: load workspace, resolve paths, detect
+changes, update obsolete files with backup rotation.
+
+Example:
+  >>> from fsync.main import main
+  >>> main()
+"""
+
+import os, sys
+from datetime import datetime
+from xaeian import JSON, INI, FILE, DIR, PATH, replace_map, Ico, Print, Color as c
+from xaeian.files import set_context
+from .args import load_args
+from . import __version__, __repo__
+
+WORKSPACE_FILE = PATH.expand("~/.fsync.txt")
+
+def main():
+  p = Print()
+  args = load_args()
+
+  if args.version:
+    print(f"FSync {c.BLUE}{__version__}{c.END}")
+    print(f"Repo: {c.GREY}https://{c.END}github.com/{__repo__}")
+    sys.exit(0)
+
+  #------------------------------------------------------------------------------------- Workspace
+  if args.workspace is not None:
+    ws = os.path.abspath(PATH.expand(args.workspace))
+    if not PATH.is_dir(ws):
+      p.err(f"Directory {c.GREY}{ws}{c.END} doesn't exist")
+      sys.exit(1)
+    FILE.save(WORKSPACE_FILE, ws)
+    p.ok(f"Set directory {c.ORANGE}{ws}{c.END} as workspace")
+    if not any([args.update, args.info, args.example, args.diff]):
+      sys.exit(0)
+
+  if not PATH.is_file(WORKSPACE_FILE):
+    p.err(f"No workspace set. Use {c.GREY}-w --workspace{c.END} to set one")
+    sys.exit(1)
+  workspace = FILE.load(WORKSPACE_FILE).strip()
+  if not PATH.is_dir(workspace):
+    p.err(f"Workspace {c.ORANGE}{workspace}{c.END} doesn't exist")
+    sys.exit(1)
+
+  set_context(root_path=workspace)
+
+  if args.example:
+    from . import example
+    example.create()
+    sys.exit(0)
+
+  #---------------------------------------------------------------------------------------- Config
+  
+  sync = JSON.load("sync.json")
+  if not sync:
+    p.err(f"Missing or invalid {c.RED}sync.json{c.END}")
+    sys.exit(1)
+  sync = {k: v for k, v in sync.items() if not k.startswith("#")}
+  if not sync:
+    p.err(f"No active entries in {c.RED}sync.json{c.END}")
+    sys.exit(1)
+  mydict = INI.load("dict.ini")
+  if not mydict:
+    p.err(f"Missing or invalid {c.RED}dict.ini{c.END}")
+    sys.exit(1)
+
+  #---------------------------------------------------------------------------------- Resolve paths
+  resolved = {}
+  for name, paths in sync.items():
+    resolved[name] = [replace_map(x, mydict, "{", "}") for x in paths]
+
+  #------------------------------------------------------------------------------------- Validate
+  errors = False
+  for name, paths in resolved.items():
+    seen = set()
+    for path in paths:
+      if not PATH.is_file(path):
+        p.err(f"Path {c.ORANGE}{path}{c.END} in {c.RED}{name}{c.END} doesn't exist")
+        errors = True
+      if path in seen:
+        p.err(f"Path {c.ORANGE}{path}{c.END} in {c.RED}{name}{c.END} duplicated")
+        errors = True
+      seen.add(path)
+  if errors:
+    sys.exit(1)
+
+  if args.diff is None:
+    p.wrn(f"Flag {c.GREY}-d{c.END} requires tag, e.g. {c.GREY}-d {c.MAGNTA}1.1{c.END}")
+    args.diff = ""
+
+  #----------------------------------------------------------------------------------------- Diff
+  diff_ctx = {}
+  if args.diff:
+    diff_ctx["latest_nbr"], diff_ctx["obsolete_nbr"] = map(int, args.diff.split("."))
+
+  #----------------------------------------------------------------------------------------- Sync
+  update_flag = False
+  nbr_last = 0
+
+  def sync_file(name:str, paths:list[str]):
+    nonlocal update_flag, nbr_last
+    paths = [PATH.normalize(x) for x in paths]
+    paths = [x for x in paths if PATH.is_file(x)]
+    if len(paths) < 2: return
+    hashs = [FILE.hash(f, algo="md5") for f in paths]
+    stamps = [FILE.mtime(f) for f in paths]
+    dts = [datetime.fromtimestamp(s).strftime("%Y-%m-%d %H:%M:%S") for s in stamps]
+    if len(set(hashs)) == 1 and not args.info: return
+    latest_id = stamps.index(max(stamps))
+    latest_hash = hashs[latest_id]
+    latest_file = paths[latest_id]
+    latest_dt = dts[latest_id]
+    nbr_last += 1
+    nbr_obsolete = 0
+    if diff_ctx and diff_ctx.get("latest_nbr") == nbr_last:
+      diff_ctx["latest_file"] = latest_file
+      diff_ctx["name"] = name
+    p(f"{Ico.INF} {c.YELLOW}{nbr_last}{c.GREY}.x{c.END} Latest"
+      f" {c.BLUE}{name}{c.END}: {c.GREY}{latest_file}{c.END}"
+      f" {c.TEAL}{latest_dt}{c.END}")
+    for file, hash, dt, stamp in zip(paths, hashs, dts, stamps):
+      tag = lambda clr: f"{Ico.GAP} {clr}{nbr_last}.{nbr_obsolete}{c.END}"
+      if hash != latest_hash:
+        update_flag = True
+        nbr_obsolete += 1
+        color = c.YELLOW
+        if(diff_ctx and diff_ctx.get("latest_nbr") == nbr_last
+            and diff_ctx.get("obsolete_nbr") == nbr_obsolete):
+          diff_ctx["obsolete_file"] = file
+          color = c.GREEN
+        if args.update:
+          backed = utils.backup_file(file, name)
+          try:
+            DIR.copy(latest_file, file)
+            msg = f"{c.GREY}{file}{c.END} updated"
+            if backed: msg += f" {c.GREY}(backup){c.END}"
+            msg += f" {c.GREEN}OK{c.END}"
+            p(f"{tag(color)} {msg}")
+          except Exception:
+            p(f"{tag(color)} {c.GREY}{file}{c.END} update {c.RED}FAILED{c.END}")
+        else:
+          p(f"{tag(color)} Obsolete: {c.GREY}{file}{c.END} {c.ORANGE}{dt}{c.END}")
+          if stamp == os.path.getctime(file):
+            p.wrn("File was created recently, make sure it's not actually newer!")
+      elif (args.update or args.info) and file != latest_file:
+        p.ok(f"{c.GREY}{file}{c.END} is up-to-date")
+
+  from . import utils
+
+  for name, paths in resolved.items():
+    sync_file(name, paths)
+
+  if not update_flag:
+    p.inf(f"All files are in the same version {c.GREY}(no update needed){c.END}")
+  elif not args.update:
+    p.run(f"Update older files using {c.YELLOW}-u{c.END} {c.GREY}--update{c.END}")
+    p.run(f"Display file changes using {c.YELLOW}-d{c.END} {c.GREY}--diff{c.END}")
+    if args.diff:
+      if not diff_ctx or "obsolete_file" not in diff_ctx:
+        p.err(f"Invalid tag {c.GREEN}{args.diff}{c.END} for comparing files")
+        sys.exit(1)
+      p.inf(f"Diff compare {c.BLUE}{diff_ctx['name']}{c.END}"
+        f" tag {c.GREEN}{diff_ctx['latest_nbr']}.{diff_ctx['obsolete_nbr']}{c.END}:")
+      reversed_dict = {PATH.normalize(v): f"{{{k}}}" for k, v in mydict.items()}
+      from . import diff
+      diff.show(diff_ctx["obsolete_file"], diff_ctx["latest_file"], reversed_dict)
+
+if __name__ == "__main__":
+  main()

fsync-1.0.0/fsync/utils.py

@@ -0,0 +1,36 @@
+# fsync/utils.py
+
+import os
+from datetime import datetime
+from xaeian import FILE, DIR, PATH
+
+BACKUP_DIR = "backups"
+BACKUP_KEEP = 10
+
+def _find_backups(name: str) -> list[str]:
+  """Find all backups for given sync name, sorted oldest first."""
+  dir = PATH.resolve(f"{BACKUP_DIR}/{name}")
+  if not os.path.isdir(dir): return []
+  return [f"{dir}/{f}" for f in sorted(os.listdir(dir))]
+
+def backup_file(path: str, name: str) -> bool:
+  """
+  Backup file before overwriting.
+  Layout: backups/ary.c/2025-02-24@14-30-00.c
+  Skips if identical to latest backup. Rotates beyond BACKUP_KEEP.
+  """
+  file_hash = FILE.hash(path, algo="md5")
+  existing = _find_backups(name)
+  if existing and FILE.hash(existing[-1], algo="md5") == file_hash:
+    return False
+  dir = PATH.resolve(f"{BACKUP_DIR}/{name}")
+  DIR.ensure(f"{dir}/")
+  ext = PATH.ext(name)
+  stamp = datetime.now().strftime("%Y-%m-%d@%H-%M-%S")
+  dst = f"{dir}/{stamp}{ext}"
+  DIR.copy(path, dst)
+  # Rotate
+  all_backups = _find_backups(name)
+  while len(all_backups) > BACKUP_KEEP:
+    os.remove(all_backups.pop(0))
+  return True

fsync-1.0.0/fsync.egg-info/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: fsync
+Version: 1.0.0
+Summary: Local file synchronization for scattered shared libraries
+Author: Xaeian
+License: MIT
+Project-URL: Repository, https://github.com/Xaeian/FSync
+Keywords: sync,files,libraries,backup
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: xaeian
+Provides-Extra: diff
+Requires-Dist: rich; extra == "diff"
+Provides-Extra: all
+Requires-Dist: rich; extra == "all"
+
+## 📖 FSync
+
+This tool **eliminates the problem of scattered libraries** by synchronizing 🔄 selected files spread across different projects on your machine _(locally)_. No more chaos and manual file copying.
+
+At first glance, centralizing libraries seems like a great idea. It makes work easier and avoids code duplication. In practice, however, some complications arise:
+
+- You don't always want to update a library in a project you're no longer developing, but it still needs to work.
+- Some libraries must be part of the repository. When you hand off/close a project, you want everything in one place, without having to pull additional dependencies from external sources.
+- It's better when all resources are in the project directory. It simplifies configuration _(Makefile, CMake)_, eliminates path and version issues, and improves IDE integration.
+
+This solution is perfect if you run many smaller projects and care about efficient library management _(code that appears across multiple projects)_. If you make frequent changes, want to avoid messy code, but don't have time to spend hours organizing dependencies: this tool is for you! The program is dead simple. What matters is efficient and effective work, without unnecessary bureaucracy. The open source community can do its thing, but here the priority is a happy client and a working project done ⚡**fast** and 👍**good enough**.
+
+### 🧐 Problems!
+
+- ❌ **Possible accidental overwrites**: if you edit two versions of a library at the same time.
+- ✅ Avoid this, but if it happens, every overwritten version is saved as a timestamped backup, so you can always recover your changes.
+- ❌ **No environment isolation**: different projects may require different versions of the same library.
+- ✅ Not a problem! Just create separate entries for different versions, keeping synchronization independent. You can also comment out entries for libraries that shouldn't be updated anymore.
+- ❌ **Code duplication across repositories**: instead of one library copy, you have several in different projects.
+- ✅ That's the point! Each client should have their own library version, with no dependencies on other repos. Full control, zero unnecessary complications.
+
+### 🤔 Alternatives?
+
+Of course you can approach this more professionally by:
+
+- Versioning libraries as separate projects/repositories and updating them as needed.
+- Using Git **Submodules**, which allows tracking library versions in the repository.
+- External package managers _(`pip`, `npm`, `cargo`)_ that simplify dependency management.
+
+If any of our libraries reach a stable version that we don't chaotically change every project, and they're good enough, it's worth considering one of the above solutions.
+
+### ⚙️ Config
+
+The **`sync.json`** file defines file synchronization configuration. Each entry is a key _(filename)_ and a list of paths to synchronize. Keys starting with `#` are treated as commented out and skipped.
+
+Paths can use shorthand notation via the **`dict.ini`** file, which defines aliases for frequently repeated locations. In `sync.json` paths you can reference these aliases using `{key}` notation.
+
+#### Example
+
+Running the program with the `-e`, `--example` flag will create example config files locally.
+
+File `dict.ini`
+
+```ini
+web = C:/Users/Me/Projects/WebPage/backend
+staff = C:/Users/Me/Desktop/MyStaff/test
+work = C:/Users/Me/Work/Drivers/repos
+```
+
+File `sync.json`
+
+```json
+{
+  "serial.c": ["{staff}/serial.c", "{work}/PLC/serial_port.c"],
+  "utils.py": ["{web}/lib/utils.py", "{work}/PLC/misc.py"],
+  "#old_lib.c": ["{staff}/old_lib.c", "{work}/legacy/old_lib.c"]
+}
+```
+
+### 📦 Install
+
+```sh
+pip install fsync        # basic
+pip install fsync[diff]  # + rich (diff display)
+```
+
+> Also available as standalone `.exe` on [GitHub Releases](https://github.com/Xaeian/FSync/releases).
+
+### 🚀 Use
+
+First, set the workspace: the directory containing your config files (`sync.json`, `dict.ini`) and where backups will be stored:
+
+```sh
+fsync -w C:/Projects/sync  # specified path
+fsync -w                   # current directory
+```
+
+Running the program generates a report:
+
+```bash
+fsync
+```
+
+To synchronize _(i.e. update older file versions)_, just add the `-u`, `--update` flag:
+
+```bash
+fsync -u
+```
+
+For each pair of files with discrepancies, tags are generated. You can use them to inspect differences between files with the `-d`, `--diff` flag:
+
+```bash
+fsync -d 1.1
+```

fsync-1.0.0/fsync.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+pyproject.toml
+readme.md
+fsync/__init__.py
+fsync/__main__.py
+fsync/args.py
+fsync/diff.py
+fsync/example.py
+fsync/main.py
+fsync/utils.py
+fsync.egg-info/PKG-INFO
+fsync.egg-info/SOURCES.txt
+fsync.egg-info/dependency_links.txt
+fsync.egg-info/entry_points.txt
+fsync.egg-info/requires.txt
+fsync.egg-info/top_level.txt

fsync-1.0.0/fsync.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

fsync-1.0.0/fsync.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fsync = fsync.__main__:main

fsync-1.0.0/fsync.egg-info/requires.txt

@@ -0,0 +1,7 @@
+xaeian
+
+[all]
+rich
+
+[diff]
+rich

fsync-1.0.0/fsync.egg-info/top_level.txt

@@ -0,0 +1 @@
+fsync

fsync-1.0.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fsync"
+version = "1.0.0"
+description = "Local file synchronization for scattered shared libraries"
+readme = "readme.md"
+license = {text = "MIT"}
+requires-python = ">=3.12"
+authors = [{name = "Xaeian"}]
+keywords = ["sync", "files", "libraries", "backup"]
+dependencies = ["xaeian"]
+
+[project.optional-dependencies]
+diff = ["rich"]
+all = ["rich"]
+
+[project.scripts]
+fsync = "fsync.__main__:main"
+
+[project.urls]
+Repository = "https://github.com/Xaeian/FSync"
+
+[tool.setuptools.packages.find]
+include = ["fsync*"]

fsync-1.0.0/readme.md

@@ -0,0 +1,94 @@
+## 📖 FSync
+
+This tool **eliminates the problem of scattered libraries** by synchronizing 🔄 selected files spread across different projects on your machine _(locally)_. No more chaos and manual file copying.
+
+At first glance, centralizing libraries seems like a great idea. It makes work easier and avoids code duplication. In practice, however, some complications arise:
+
+- You don't always want to update a library in a project you're no longer developing, but it still needs to work.
+- Some libraries must be part of the repository. When you hand off/close a project, you want everything in one place, without having to pull additional dependencies from external sources.
+- It's better when all resources are in the project directory. It simplifies configuration _(Makefile, CMake)_, eliminates path and version issues, and improves IDE integration.
+
+This solution is perfect if you run many smaller projects and care about efficient library management _(code that appears across multiple projects)_. If you make frequent changes, want to avoid messy code, but don't have time to spend hours organizing dependencies: this tool is for you! The program is dead simple. What matters is efficient and effective work, without unnecessary bureaucracy. The open source community can do its thing, but here the priority is a happy client and a working project done ⚡**fast** and 👍**good enough**.
+
+### 🧐 Problems!
+
+- ❌ **Possible accidental overwrites**: if you edit two versions of a library at the same time.
+- ✅ Avoid this, but if it happens, every overwritten version is saved as a timestamped backup, so you can always recover your changes.
+- ❌ **No environment isolation**: different projects may require different versions of the same library.
+- ✅ Not a problem! Just create separate entries for different versions, keeping synchronization independent. You can also comment out entries for libraries that shouldn't be updated anymore.
+- ❌ **Code duplication across repositories**: instead of one library copy, you have several in different projects.
+- ✅ That's the point! Each client should have their own library version, with no dependencies on other repos. Full control, zero unnecessary complications.
+
+### 🤔 Alternatives?
+
+Of course you can approach this more professionally by:
+
+- Versioning libraries as separate projects/repositories and updating them as needed.
+- Using Git **Submodules**, which allows tracking library versions in the repository.
+- External package managers _(`pip`, `npm`, `cargo`)_ that simplify dependency management.
+
+If any of our libraries reach a stable version that we don't chaotically change every project, and they're good enough, it's worth considering one of the above solutions.
+
+### ⚙️ Config
+
+The **`sync.json`** file defines file synchronization configuration. Each entry is a key _(filename)_ and a list of paths to synchronize. Keys starting with `#` are treated as commented out and skipped.
+
+Paths can use shorthand notation via the **`dict.ini`** file, which defines aliases for frequently repeated locations. In `sync.json` paths you can reference these aliases using `{key}` notation.
+
+#### Example
+
+Running the program with the `-e`, `--example` flag will create example config files locally.
+
+File `dict.ini`
+
+```ini
+web = C:/Users/Me/Projects/WebPage/backend
+staff = C:/Users/Me/Desktop/MyStaff/test
+work = C:/Users/Me/Work/Drivers/repos
+```
+
+File `sync.json`
+
+```json
+{
+  "serial.c": ["{staff}/serial.c", "{work}/PLC/serial_port.c"],
+  "utils.py": ["{web}/lib/utils.py", "{work}/PLC/misc.py"],
+  "#old_lib.c": ["{staff}/old_lib.c", "{work}/legacy/old_lib.c"]
+}
+```
+
+### 📦 Install
+
+```sh
+pip install fsync        # basic
+pip install fsync[diff]  # + rich (diff display)
+```
+
+> Also available as standalone `.exe` on [GitHub Releases](https://github.com/Xaeian/FSync/releases).
+
+### 🚀 Use
+
+First, set the workspace: the directory containing your config files (`sync.json`, `dict.ini`) and where backups will be stored:
+
+```sh
+fsync -w C:/Projects/sync  # specified path
+fsync -w                   # current directory
+```
+
+Running the program generates a report:
+
+```bash
+fsync
+```
+
+To synchronize _(i.e. update older file versions)_, just add the `-u`, `--update` flag:
+
+```bash
+fsync -u
+```
+
+For each pair of files with discrepancies, tags are generated. You can use them to inspect differences between files with the `-d`, `--diff` flag:
+
+```bash
+fsync -d 1.1
+```

fsync-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+