# update-nix-fetchgit
This is a command-line utility for updating fetcher calls in
[Nix](http://nixos.org/nix/) expressions. It has two primary purposes:
- Automating the process of keeping such expressions up-to-date with the latest
sources
- Filling hashes automatically instead of copying from the error message<sup>[1](#deny)</sup>.
The following fetchers are supported:
- `fetchgit`
- `fetchgitPrivate`
- `fetchFromGitHub`
- `fetchFromGitLab`
- `builtins.fetchGit`
- `builtins.fetchTarball` (Only updates the url when this is a archive fetch
from GitHub)
- `pkgs.haskellPackages.callHackageDirect` (Only updates the hash)
The options `deepClone`, `leaveDotGit`, `fetchSubmodules` are also supported.
Additionally if the `rev` (for git fetches) or `url` attribute has a comment:
- `pin`: the revision or URL will not be updated, only the hash will be
changed
- Anything else: the `rev` or `url` parameter will be updated to point to the
revision pointed to by the branch or tag named in the comment. This is in the
format expected by `git ls-remote` so if the expression has `rev = _; #
tags/v*` it will be updated to the latest tag beginning with `v`, sorted by
version.
## Usage
### As a command line tool
Pass the name of the files to be updated in place or pass no files to read and
write to `stdin` and `stdout` (useful as a filter in an editor).
`update-nix-fetchgit file1.nix file2.nix`
`update-nix-fetchgit <file1.nix >file1-updated.nix`
It will update fetchers anywhere in the files, note that it is a purely
syntactic match so complicated invocations of the fetchers may not be picked
up; see [./src/Update/Nix/Updater.hs](./src/Update/Nix/Updater) to look at the
shapes of Nix expressions which are matched.
If you pass `--only-commented` only expressions which have a comment on the
`rev` or `url` attribute will be updated. This can be useful for updating files
en-mass with some control over which expressions are modified with a command
like: `fd .nix --exec update-nix-fetchgit --only-commented`
Please open an issue if `update-nix-fetchgit` doesn't recognize a fetcher and
you think it could.
### From Vim
This VimScript will bind `<leader>u` to update the fetcher under the cursor.
The mnemonic is `u` for "it's un*U*sual to update things in this way"
```viml
" A helper to preserve the cursor location with filters
function! Preserve(command)
let w = winsaveview()
execute a:command
call winrestview(w)
endfunction
" Update fetcher under cursor, note that this might take a little while if the
" fetched path is large.
autocmd FileType nix map <nowait> <leader>u :call Preserve("%!update-nix-fetchgit --location=" . line(".") . ":" . col("."))<CR>
```
[](https://asciinema.org/a/fJesaOF7jGKjYcLtUCsOqrZX6)
## Examples
Here are some examples of nix expressions which can be updated:
- Updating `src` and `version`
```nix
{ stdenv, fetchgit }:
stdenv.mkDerivation rec {
name = "foo-${version}";
version = "2016-07-13";
# ^ version will be updated to the date of the new revision
src = fetchgit {
url = "git://midipix.org/slibtool";
rev = "4f56fd184ef6020626492a6f954a486d54f8b7ba";
# ^ rev will be updated to the revision of HEAD
sha256 = "0nmyp5yrzl9dbq85wyiimsj9fklb8637a1936nw7zzvlnzkgh28n";
# ^ sha256 will be updated to the correct hash
};
}
```
- Following a branch fetched with `builtins.fetchTarball`
```nix
{ pkgs ? import (builtins.fetchTarball {
url =
"https://github.com/NixOS/nixpkgs/archive/foobar.tar.gz"; # nixos-unstable
# ^ 'foobar' will be replaced with the revision pointed to by 'refs/heads/nixos-unstable'
sha256 = "";
# ^ sha256 will be updated to the correct hash
}) { } }:
myExpression
```
- Updating the hash (instead of trying to build and copying the hash from the
error message)
```nix
{
upfind = import (pkgs.fetchFromGitHub {
owner = "expipiplus1";
repo = "upfind";
rev = "cb451254f5b112f839aa36e5b6fd83b60cf9b9ae"; # pin
# ^ This will not change because of the '# pin' comment
sha256 = _;
# ^ This will be updated
}) { };
}
```
## Mechanism
When you run `update-nix-fetchgit` on a file, it will:
- Read the file and parse it as a Nix expression.
- Find all calls to fetchers.
- Run
[`nix-prefetch-git`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/fetchgit/nix-prefetch-git)
or `nix-prefetch-url` (and a call to the GitHub API to get the commit date in
the case of `builtins.fetchTarball`) to get information about the latest
version.
- Update the corresponding `rev`, `sha256`, `url`, and `version` attributes for
each repository.
- Overwrite the original input file or print to `stdout`
Any `version` attribute found in the file will be updated if it is in a set
that contains (directly or indirectly) a Git fetch. The version attribute will
be updated to the commit date of the latest HEAD commit in the Git repository,
in the time zone of the committer, in "YYYY-MM-DD" format. If the set contains
multiple Git fetches, the latest such date is used.
## Building from source
The recommended way to build this program from source for development purposes
is to download and run `nix-shell` in the top-level source directory and then
run `cabal build`.
# Authors
- [expipiplus1](https://github.com/expipiplus1) - I'm `jophish` on Freenode; say hi!
- [DavidEGrayson](https://github.com/DavidEGrayson)
--------
<a name="deny">1</a>: Don't deny you do it