This is both documentation and a design document (the latter at this stage anyway). Many things here aren't implemented.
Forkage is a simple package manager that encourages forking packages for tweaking, and searching others' forks. With the current goal of supporting git and common git hosts.
fkg install gh:MichaelBelousov/forkage
fkg install github.com:MichaelBelousov/forkage
fkg install github.com:MichaelBelousov/forkage/branch
fkg install MichaelBelousov/forkage # if you choose a default provider
fkg i MichaelBelousov/forkage
# when installing a specific revision, if you already have it installed unambiguously you can drop the
# leading qualifier
fkg i [email protected] # use git tag
fkg i forkage@0adf18 # use git commit
# if you somehow need two different versions of one package, use --unique installs
fkg i --unique [email protected] # includes the tag in the package directory's name
fkg uninstall forkage # will work if unambiguously installed
fkg remove forkage
fkg update gh:MichaelBelousov/forkage
fkg upgrade forkage # will work if unambigous
fkg merge forkage --ref origin/branch
fkg merge forkage --ref gh:Alice/forkage/branch
fkg rebase forkage
fkg merge forkage --vcs-args rebase --interactive
fkg config set default-provider github.com
fkg config get default-provider
fkg config set search-providers github.com,gitlab.com,src.ht
fkg config list
fkg provider github login # opens a github integration page for authorizing a token
fkg fork MichaelBelousov/forkage # will create a fork for your user using the github API
fkg fork --as myorg MichaelBelousov/forkage # will create a fork in an organization that you have authorized
# at install time you choose default searched providers
fkg search forkage
# but you can specify
fkg search gh:forkage
# list all forks for each result
fkg search --forks gh:forkage
# look at installed packages if they exist
fkg info forkage
# can also show extended information of remote package
fkg info gh:MichaelBelousov/forkage
fkg list # list all installed packages
# diff our version vs some branch
fkg diff forkage @master # can use unqualified branch/ref
# this is basically like creating a new repo on a provider and git cloning it
fkg init Name # create a package (repo) for your user on your default provider
fkg init gl:Org/Name # create a package under a specific provider and organization
# do something in the package's directory
fkg do gh:MichaelBelousov/forkage git ls-files
fkg do forkage git diff master
Packages are installed to the nearest forkage
directory, ascending from the current directory's path.
If there are none, a new forkage
directory is created in the current directory.
A config file will be searched for in order:
.forkageconfig
next to the nearestforkage
directory ascending the current directory's path.$HOME/.forkageconfig
/etc/forkageconfig
An example git provider URL of https://github.com/MichaelBelousov/forkage
would be installed as:
./forkage/github.com/MichaelBelousov/forkage
A unique install (fkg i --unique gh:MichaelBelousov/[email protected]
) would install to a unique directory:
./forkage/github.com/MichaelBelousov/[email protected]
The URL's path delimiters are translated to file system path delimiters.
Next to the forkage
directory will be placed a forkagelist
file capturing the packages in the project.
The format is .ini
[forkage]
address = https://github.com/MichaelBelousov/forkage
locked = 0123456789abcdef
reference = master
unique = false
[[email protected]]
address = https://github.com/MichaelBelousov/forkage
locked = 7654321089dcbaef
reference = 0.1
unique = true
Haven't thought this one out yet. Technically if the package uses forkage, we can recurse.
Consider npm dependencies though: a package containing JavaScript source of an npm package could configure a workspace manager
like pnpm
to include all forkage/*
directories in the workspace so that they participate
in workspace dependency resolution and even build commands.