[Request] Create better documentation for Lockable attribute and locks in general

[Ecnassianer]

There isn't a lot of great documentation for the lockable attribute at the moment.

Some specific areas of vagueness:
When I push a locked file and release the locks, when can other users edit those files? Are locks time based, or do the propagate through branches? How do they propagate through branches?

When should I apply the lockable attribute? Does lockable actually mean "this file type (pattern) requires locking before editing"? All files can be locked, regardless of whether they have the lockable attribute, right? But lockable ones should not be edited without a lock? Are there other implications of the lockable attribute?

Here's a relevant issue where we were discussing whether lockable was the attribute we should check in a git client. I made an inference from the fact that lockable makes files readonly, but I'd rather have it be more explicit in the documentation:
github-for-unity/Unity#949

Thank you!

[bk2204]

Hey, thanks for bringing this to our attention, and sorry about the documentation being unhelpful. I definitely agree that we can improve the documentation here, and I'll try to get some of this down. Can you say a few words about where you looked in the documentation so I know how best to improve things?

Locks are currently global; they apply to all branches, and other users can forcibly unlock them if they want (assuming the server doesn't prevent that). The locks are checked on push assuming that the lfs.<url>.locksverify flag is set, or that the server does that check independently.

To answer your question about the lockable attribute, there's this piece in git-lfs-config(5) that describes the lfs.setlockablereadonly flag:

These settings...control whether files marked as 'lockable' in git lfs track are made read-only in the working copy when not locked by the current user. The default is true; you can disable this behaviour and have all files writeable by setting either variable to 0, 'no' or 'false'.

The lockable attribute essentially is a way to indicate that you want this behavior for these files. So when you asked if this means the pattern requires locking before editing, you were completely correct. All files can be locked, but the idea is to make it harder to edit these ones without a lock.

The lockable attribute doesn't have any other side effects; it's solely limited to this behavior.

As I mentioned, I'll see if we can get this documented a little bit better so that it's easier to find and more straightforward to understand.

[Ecnassianer]

I did a bunch of googling for using Git LFS with Unity and other game development tools, and most of what I found was blog posts about how to set up your .gitattributes for Unity, but they were mostly just "Here's mine, try using it" without much explanation of why each attribute was applied.

The Git LFS tutorial was useful, and this seems to be the sum total of official documentation on locking:
https://github.com/git-lfs/git-lfs/wiki/File-Locking
But it lacks the detail to convince me that I'm making the configuration choices that fit my use case.

The one place I didn't look very deeply was the conversations in GitHub issues, since each time I started down those threads they seemed like they were likely only applicable to past problems that came up during development. There might be a lot of documentation there if someone could confirm that it is still applicable.

git-lfs-config(5)

Is that a man page? Is this online anywhere? I use a GUI client, so I haven't looked at a man page since I was dual-booting Linux. XD

lfs.setlockablereadonly

I have seen this string come up in Stack Exchange questions, but couldn't figure out where it's set. Does it go in the .gitattributes file? Sorry, this is probably a git fundamental that I don't know. I am still relatively new to git, since before Git LFS all my projects required using either Perforce or Plastic SCM. In any case, from what you've said above, I think I want the default, so I'm probably good.

Thanks for clarifying these points. They make me think I set things up properly in my repository.

Can you elaborate on the global locks a bit. Say I'm working in dev and I lock meme.jpg. Someone working in master won't be able to lock meme.jpg on master, because I have the global lock. Then I push my changes to meme.jpg, but I don't merge back to master just yet. I release the lock because I'm done with it in dev. What happens when someone working on master tries to lock meme.jpg? For my case, they shouldn't be able to, since they don't have the changes I made in dev yet, it should still be locked for them. Does Git LFS work that way?

[Ecnassianer]

Also, from your explanation, I think I'm going to change the title to "documentation for locks", since my questions seem to be a bit broader than the lockable attribute specifically.

[bk2204]

git-lfs-config(5)
Is that a man page? Is this online anywhere? I use a GUI client, so I haven't looked at a man page since I was dual-booting Linux. XD

It is indeed. You can also see them if you go to the Git LFS website and then click “Docs”. That will take you to the main repo, which you can click on man to see the manual pages.

All of the lfs. options generally go in one of your Git configuration files. The git config docs will tell you where you can find all of those files (see the “FILES” section); there are ones per-repository, per-user, and per-system. There's also the .lfsconfig file in your repo which can accept only a limited set of options (for security reasons). The docs for git-lfs-config explain which those are.

Can you elaborate on the global locks a bit. Say I'm working in dev and I lock meme.jpg. Someone working in master won't be able to lock meme.jpg on master, because I have the global lock. Then I push my changes to meme.jpg, but I don't merge back to master just yet. I release the lock because I'm done with it in dev. What happens when someone working on master tries to lock meme.jpg? For my case, they shouldn't be able to, since they don't have the changes I made in dev yet, it should still be locked for them. Does Git LFS work that way?

It doesn't currently. While you're holding the lock, other people cannot acquire the lock, and other people cannot push a modification to the file, but when the lock is released, anyone can acquire it, regardless of whether your changes have been merged into their branch. There is a proposal to have per-branch locks, where you could lock master and dev and then unlock master once dev has been merged in, but it isn't implemented yet.

I appreciate you pointing out that you looked at the wiki; we have unfortunately been neglecting it somewhat recently, and I think trying to improve that will be helpful for both you and others.