This PR adds the ability to checkout old versions of files from the git history. In its plain form, it presents the user with a git log that includes, for each commit, an index (HEAD=1), the short form of that revision's hash, the commit message, and a list of which files changed (additions, deletions, modifications). The user is then prompted to select a specific commit. Either an index or a short hash is valid. Anything else, aborts the operation.
Other forms of the command:
gin version --json: prints a git log in JSON format.
gin version --max-count N (short version -n N): limit log entries (same as for git). If this isn't specified, it's limited to 10 by default (or the maximum number of revisions if it's < 10). If 0 is used, it prints all revisions.
gin version --id REV: does not print a log and does not prompt the user, instead it immediately checks out the revision specified by REV. This is meant to be used with a short hash, but no checks are made by the client if the revision is a hash or anything else. This is intentional since it allows the user to specify any valid git revision name (tags, relative revisions such as HEAD~3, etc).
gin version <filepaths>: limits revisions and checkout to files and paths that match the argument, for reverting specific files, directories, or globs.
The above forms can be combined, though some combinations might not make sense. For example, if the user runs gin version --max-count 3 --id 0690d9a, the --max-count argument is ignored, since the prompt is skipped.
When files are reverted to older versions, a new commit (and upload) is performed to save the version change. This allows users to switch between versions while also keeping an immediate history of these version changes. The push (upload) should be quick, even if checking out old large files, since the content (presumable) already exists on the remote. This might change in the future with the addition of commits without push.
Other changes
Fixes #185: Excluded files were sometimes added to git-annex. This was introduced after a change in the way gin lock is handled, which performed an 'add' without specifying the exclusion criteria.
Logging: Saves user command to log file with all arguments.
Error messages: A few error messages were improved with more information and passthrough of stderr when the cause is unexpected.
Not implemented
The original plan for gin version included the option to specify a target location to copy a checked out version of a single file. The use case would be for the user to checkout an old version of a file without overwriting the current one. This has turned out to be tricky for annexed files, so I'm postponing it for now. Also, it will be easier to review this PR without the additional functionality, which will come in another, simpler PR.
New command: gin version
This PR adds the ability to checkout old versions of files from the git history. In its plain form, it presents the user with a git log that includes, for each commit, an index (HEAD=1), the short form of that revision's hash, the commit message, and a list of which files changed (additions, deletions, modifications). The user is then prompted to select a specific commit. Either an index or a short hash is valid. Anything else, aborts the operation.
Other forms of the command:
gin version --json: prints a git log in JSON format.gin version --max-count N(short version-n N): limit log entries (same as for git). If this isn't specified, it's limited to 10 by default (or the maximum number of revisions if it's < 10). If 0 is used, it prints all revisions.gin version --id REV: does not print a log and does not prompt the user, instead it immediately checks out the revision specified byREV. This is meant to be used with a short hash, but no checks are made by the client if the revision is a hash or anything else. This is intentional since it allows the user to specify any valid git revision name (tags, relative revisions such asHEAD~3, etc).gin version <filepaths>: limits revisions and checkout to files and paths that match the argument, for reverting specific files, directories, or globs.The above forms can be combined, though some combinations might not make sense. For example, if the user runs
gin version --max-count 3 --id 0690d9a, the--max-countargument is ignored, since the prompt is skipped.When files are reverted to older versions, a new commit (and upload) is performed to save the version change. This allows users to switch between versions while also keeping an immediate history of these version changes. The push (upload) should be quick, even if checking out old large files, since the content (presumable) already exists on the remote. This might change in the future with the addition of commits without push.
Other changes
gin lockis handled, which performed an 'add' without specifying the exclusion criteria.Not implemented
The original plan for
gin versionincluded the option to specify a target location to copy a checked out version of a single file. The use case would be for the user to checkout an old version of a file without overwriting the current one. This has turned out to be tricky for annexed files, so I'm postponing it for now. Also, it will be easier to review this PR without the additional functionality, which will come in another, simpler PR.