This post is moved from the git-annex-adjust manpage, thanks @joey for the hint on where to put it
Adjusted branches are important to my data science project, because my programs cannot deal with the read-only symlinks to annex'ed files.
But I find this command confusing, especially that
Calling on an unlocked adjusted branch,
git annex adjust --unlockpropagates commits back to the master branch differently thangit annex sync --no-push --no-pull --no-contentdoes.I can't find a way to "un-adjust" a branch without resorting to lower-level git commands.
Problem 1:
Say I have done git annex adjust --unlock and then have done more commits. The history now looks like this:
* My new commit 2 (HEAD -> adjusted/master(unlocked))
* My new commit 1 (HEAD -> adjusted/master(unlocked))
* git-annex adjusted branch
* Last old commit (master, basis/adjusted/master(unlocked))
* Previous commits
If I execute now git annex adjust --unlock again, the commits are propagated back to the original branch, but my HEAD is still on the original adjusted branch. So both the master branch and my adjusted branch grow over time which clutters the history and is confusing.
* My new commit 2 (master)
| * My new commit 2 (HEAD -> adjusted/master(unlocked))
* | My new commit 1
| * My new commit 1
| * git-annex adjusted branch
|/
* Last old commit (basis/adjusted/master(unlocked))
* Previous commits
On the other hand, if I do git annex sync --no-push --no-pull --no-content, the commits are propagated back to master, and a new adjusted branch is created on top of that:
* git-annex adjusted branch (HEAD -> adjusted/master(unlocked))
* My new commit 2 (master, basis/adjusted/master(unlocked))
* My new commit 1
| * My new commit 2 [abandoned old adjusted branch]
| * My new commit 1
| * git-annex adjusted branch
|/
* Last old commit
* Previous commits
This behaviour makes much more sense to me! Why does it take the modified sync command to do this? Why is this not done as well when re-calling git annex adjust --unlock? The sync command seems a counter-intuitive place to do this, using the adjust command would be far more intuitive for me and I think also for other users.
Problem 2
I see no easy way of "un-adjusting" an adjusted branch. Currently I do
git sync --no-push --no-pull --no-content
git checkout master
git branch -D "adjusted/master(unlock)"
git branch -D "refs/basis/adjusted/master(unlock)"
That's a lot of text for the inverse operation of git annex adjust --unlock and also I have to take care myself to not forget and loose commits I did on the adjusted branch. Did I miss an easier way? If not, I think it would be a great addition.
Re-running
git-annex adjustwhen you're already in that adjusted branch avoids pulling any changes from the original branch into the branch. It only propagates changes you've made back over to the original branch.Running
git-annex syncpulls in changes from the original branch before propagating commits. That pull happens to result in the git history shape you like.Re-running
git-annex adjustreally only became much of a thing at all to support--hide-missingand--unlock-present, which both make an adjusted branch that may need to be updated even without pulling from the original branch. I don't think it has much utility in an--unlockbranch. The man page says to usegit-annex syncbefore mentioning re-running it.As far as un-adjusting goes, it's basically a matter of
git checkoutof the original branch, which is easy enough. The rest of your commands involve propagating changes from it back to the original branch, which it seems to me someone may or may not want to do, depending on what happened to their adjusted branch. I suppose that deleting the basis branch ref does argue in favor of making a git-annex command to handle this, but it seems to me all that ref is going to do when not deleted is cause a small number of git objects to not get gc'd later in an unusual circumstance (when the original branch gets rebased).