{"id":18120166,"url":"https://github.com/tiesselune/git-jam","last_synced_at":"2025-04-14T17:12:42.648Z","repository":{"id":22039133,"uuid":"25367499","full_name":"tiesselune/git-jam","owner":"tiesselune","description":"Yet another binary manager for git, largely inspired by git-fat, but aimed at being more cross-platform","archived":false,"fork":false,"pushed_at":"2018-01-19T17:49:18.000Z","size":87,"stargazers_count":6,"open_issues_count":3,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-10T10:17:19.935Z","etag":null,"topics":["binary-data","git","git-jam","javascript","npm-package"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tiesselune.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-10-17T16:44:27.000Z","updated_at":"2023-10-22T10:24:53.000Z","dependencies_parsed_at":"2022-08-18T21:20:24.356Z","dependency_job_id":null,"html_url":"https://github.com/tiesselune/git-jam","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiesselune%2Fgit-jam","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiesselune%2Fgit-jam/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiesselune%2Fgit-jam/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiesselune%2Fgit-jam/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tiesselune","download_url":"https://codeload.github.com/tiesselune/git-jam/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248801568,"owners_count":21163683,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["binary-data","git","git-jam","javascript","npm-package"],"created_at":"2024-11-01T05:18:38.514Z","updated_at":"2025-04-14T17:12:42.619Z","avatar_url":"https://github.com/tiesselune.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"git-jam\n=======\n![Git-jam logo](https://raw.githubusercontent.com/tiesselune/git-jam/master/git-jam.png)\n___\nYet another binary manager for git, largely inspired by git-fat, but aimed at being more cross-platform\n\n\n\n## TL;DR\n\n    //Installation\n    git clone https://github.com/tiesselune/git-jam.git\n    cd git-jam\n    sudo npm install -g\n\n    //Configuration\n    git jam init\n    git jam filter \"*.png\"\n\n    //Usage\n    git add somefile.png\n    git commit -m \"Some commit message\"\n    git jam push\n\n    git checkout someOtherBranch\n    git jam pull\n\n\n\n## Why git-jam?\n\n`git-jam` is aimed at giving an alternative to [git-fat](https://github.com/jedbrown/git-fat), but using the same mechanics.\n\nThe main problems I encountered in `git-fat` (although it's a great tool) are:\n\n * Windows use. Configuration of `git-fat` under windows has proven being a lot of sweat, especially when installing the system to more and more computers\n * Rsync. Though rsync is great, we had to install cygwin to use it under windows when a simple SCP would have suited our needs.\n * Speed. Some things are being merged into `git-fat` to increase its speed and usability. But as our project grew, `git fat` operations grew slower and slower.\n\n## What's new?\n\n**The first concern** is cross-platform compatibility to ease configuration under windows and remove cygwin as a dependency (which forced to have two environments set up, one for use with windows GUI versionning tools and the other being rsync-enabled cygwin environment). Especially when cygwin and windows versions of git had to be set up differently.\n\nFor that purpose, I've chosen to develop it with **Javascript and Node.js**, as it has become a cross-plaform guarantee for scripts and CLI tools.\n\nRsync won't be a dependency anymore, as I have chosen to copy files directly via SSH and track changes with a file-based system.\n\n## Installing\n\n### Using npm\n\nUse NPM to install git-jam:\n\n    npm install -g git-jam\n\n### By cloning\n\nClone the project:\n\n    git clone https://github.com/tiesselune/git-jam.git\n\nThen install it using npm:\n\n    cd git-jam\n    sudo npm install -g\n\n## Usage\n\n### Configuration\nTo enable git-jam, inside a git repo, run :\n\n    git jam init\n\nIf your git repo is a git-fat enabled repo, use the `-f` or `--fat-import` option to transfer filters and objects to the jam system.\n\n    git jam init -f\n\n\u003e It does not matter whether you cloned your git repository from an existing git-jam enabled repo or just created a new one. You should call `git jam init` each time you clone a repo for which you wish git jam will work.\n\nThen define some files to be managed by `git-jam`.\n\n    git jam filter \"*.png\"\n    git jam filter \"*.jpg\"\n    git jam filter \"SomeHugeVideo.mp4\"\n\n\u003eThese commands will create entries in your `.gitattributes` file. If this file is committed, then you won't have to add those filters again the next time you clone your repo.\n\n\u003e**Don't forget to use double quotes around your pattern : it will be matched otherwise.**\n\nYou can now configure your backend.\n\n### Setting a configuration key-value pair.\n\n**These should be handled when initializing `git-jam`. If you want to manually handle git-jam's configuration, you can refer to this guide :**\n\nThere are two places for configuration in git-jam.\n\n 1. the `.jamconfig` file\n 2. the repository config file.\n\n\u003e Everything you save in the `.jamconfig` file can be committed so that every clone automatically inherits these values. The values you set in your git config files will remain on your local clone.\n\nTo save a value to the `.jamconfig` file, use the -g option:\n\n    git jam config -g \u003cparam\u003e \u003cvalue\u003e\n\nTo save a value to the normal git config, use:\n\n    git jam config \u003cparam\u003e \u003cvalue\u003e.\n\n\u003e If a key exists in both the `.jamconfig` file and in the local git config, local git config will be preferred. That way you can locally override options in `.jamconfig`.\n\n### Backends :\n\nThe main goal `git-jam` is to handle binary or large files out of the git tree.\nVersions of these files should still be saved somewhere. To be more flexible than `git-fat`, `git-jam` allows different backend solutions:\n\nCurrently, those backends are supported:\n\n   1. SFTP (FTP through SSH, available wherever SSH exists)\n   2. Amazon S3.\n\nInteractive configuration of those backends should happen when running\n\n    git jam init\n\n### Jam file workflow\n\nOnce you defined your filters, you can add your files to the index the way you would do it normally:\n\n    git add somefile.png\n    git commit -m \"My commit\"\n\nThere are two ways of synchronizing files with your backend:\n\n    1. Git-hooks\n    1. Manual push and pull\n\n#### Manual push and pull\n\nIn order to have your files synchronised with your backend, you must invoke\n\n    git jam push\n\nWhen you checkout a branch, all filtered files will be text reprensentations of your files. Use\n\n    git jam pull\n\nto fetch and replace them with their actual content.\n\n#### Git hooks.\n\nGit provides `pre-push`, `post-checkout` and `post-merge` hooks to invoke custom operations.\n\n`git-jam` comes with a simple way to setup those hooks to automatically invoke `git jam push` and `git-jam pull` on those operations.\n\nJust run\n\n    git-jam setup-hooks\n\nin your repository's folder and those hooks will be installed, automatically invoking `git-jam push` and `git-jam pull` on your behalf when doing push, pull and checkout operations in git.\n\n\n## Using `git-jam` in `gitolite`\n\n[`gitolite`](http://gitolite.com/gitolite/index.html) is a popular server backend for git, as it provides fairly easy setup and good flexibility. It is not very hard to setup `gitolite` to use `git-jam`. Here is how:\n\nBy default `gitolite` does not support sftp, which `git-jam` uses to move the binary files to and from the server. To add sftp support to gitolite you need to do the following things.\n\n* In your `.gitolite.rc` under the `ENABLE` section is a `COMMANDS` block. Add `'sftp-server',` to it (don't forget the comma):\n\n\n```\nENABLE =\u003e [\n\n    # COMMANDS\n\n        # These are the commands enabled by default\n        'help',\n        'desc',\n        'info',\n        'perms',\n        'writable',\n\n        'lock',\n\n        # Used by git-jam\n        'sftp-server',\n```\n\n* Find the commented out value for `LOCAL_CODE` and enable it for `$ENV{HOME}/local`:\n\n```\n    # suggested locations for site-local gitolite code (see cust.html)\n\n        # this one is managed directly on the server\n        LOCAL_CODE                =\u003e  \"$ENV{HOME}/local\",\n\n```\n\n* Create the actual command executable. In your `gitolite3` home directory create a subdirectory `local` with a subdirectory `commands`. In there create a link to the OpenSSH `sftp-server` executable, probably something like this:\n\n`ln -sf /usr/libexec/openssh/sftp-server local/commands/sftp-server`\n\n* Unfortunately the way OpenSSH handles sftp and the way gitolite expects local commands don't work well together. To make it work it is necessary to change the OpenSSH configuration. In your `/etc/ssh/sshd_config` change the `Subsystem sftp /usr/libexec/openssh/sftp-server` line to\n\n`Subsystem\tsftp\tsftp-server`\n\nThe problem with this is that it disables `sftp` support for other users. If that is important you will have to add the `/usr/libexec/openssh` path to the user's `PATH`.\n\n**Warning!** Every change to `sshd_config` can have security consequences! Don't use this on a server where you have to worry about your users trying to do bad things, or on a public facing server if you're not sure what it does!\n\n* Copy the `gitolite` SSH key to `${HOME}/.ssh/id_rsa` for `git-jam` to pick it up correctly.\n\nThat should be it. Enjoy!\n\n\n## What about other storage options?\n\nOther storage options are to be considered, but are not my priority for the time being. Rsync should be fairly easy to implement, for instance, to have a fully git-fat compatible repository.\n\nIf you want to implement your own, you'd have to create a new node module in `modules/Backends`, exposing 2 functions :\n\n    exports.PushFiles(\u003cstring\u003e jamPath, \u003cstring array\u003e digests)\n    exports.PullFiles(\u003cstring\u003e jamPath, \u003cstring array\u003e digests)\n\n * PushFiles must save the files (enumerated in the `digest` array) found under the `jamPath` directory to a remote location and return a promise to an array of the digests that could not be pushed.\n * PullFiles must get the files (enumerated in the `digest` array) from the remote location and save them under the `jamPath` directory and return a promise to an array of the digests that could not be pulled.\n\nThen, just set your config to the name of your backend using `git jam config`.\n\n### Example\n\nLet's say you want a rsync backend.\n\n 1. Create a `rsync.js` module in `modules/Backends`\n 2. Implement PushFiles and PullFiles functions\n 3. Execute `git jam config backend rsync`\n 4. Enjoy.\n 5. Feel free to submit a pull request with your awesome backend.\n\n\u003e Inside the PullFiles and PushFiles functions, you can use the jam config to configure your rsync backend. To access a jam config value, use `require('../gitUtils.js').jamConfig(key)`.\n\n## License\n\n`git-jam` is licensed under the MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftiesselune%2Fgit-jam","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftiesselune%2Fgit-jam","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftiesselune%2Fgit-jam/lists"}