{"action":"created","issue":{"url":"https://api.github.com/repos/chef/chef-docs/issues/552","labels_url":"https://api.github.com/repos/chef/chef-docs/issues/552/labels{/name}","comments_url":"https://api.github.com/repos/chef/chef-docs/issues/552/comments","events_url":"https://api.github.com/repos/chef/chef-docs/issues/552/events","html_url":"https://github.com/chef/chef-docs/issues/552","id":90142019,"number":552,"title":"Explain the git resource's `checkout_branch` more clearly","user":{"login":"danielsdeleo","id":37162,"avatar_url":"https://avatars.githubusercontent.com/u/37162?v=3","gravatar_id":"","url":"https://api.github.com/users/danielsdeleo","html_url":"https://github.com/danielsdeleo","followers_url":"https://api.github.com/users/danielsdeleo/followers","following_url":"https://api.github.com/users/danielsdeleo/following{/other_user}","gists_url":"https://api.github.com/users/danielsdeleo/gists{/gist_id}","starred_url":"https://api.github.com/users/danielsdeleo/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/danielsdeleo/subscriptions","organizations_url":"https://api.github.com/users/danielsdeleo/orgs","repos_url":"https://api.github.com/users/danielsdeleo/repos","events_url":"https://api.github.com/users/danielsdeleo/events{/privacy}","received_events_url":"https://api.github.com/users/danielsdeleo/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":5,"created_at":"2015-06-22T16:07:49Z","updated_at":"2015-06-23T21:10:53Z","closed_at":null,"body":"Cf. https://github.com/chef/chef/pull/3289\r\n\r\nAs I wrote there:\r\n\r\n----\r\n\r\nThe git provider is designed to work two ways:\r\n\r\n1. You want to always sync a particular commit (which can change over time based on use of attributes, etc.). In this case you identify what commit you want from the upstream repo using the `revision` property of the git resource. The git provider will locally maintain its own branch and force it to whatever commit you want. This way, if you want to switch from one branch to another, or only deploy certain tags (maybe you set with attributes or a data bag item), you just set the `revision` and the provider will always ensure you're on the correct commit by checking `git ls-remote` on the upstream repo.\r\n\r\n2. You want to do a one-time checkout. Usually this happens when you're maintaining developers' laptops with Chef. In this case, you set `enable_checkout` to false which prevents the git provider from attempting to checkout master to master. This usage was sort of bolted on to the git provider after use case (1), so it's a bit unwieldy, I admit.\r\n\r\n----\r\n\r\nWhat we're seeing is some users come to believe that the `checkout_branch` option is what they should use to specify what branch/tag/commit they want the provider to sync. We should explain clearly that this is what `revision` is for, and `checkout_branch` is only applicable for use case (2) OR if the user has a branch named \"deploy\" on their upstream repo.\r\n\r\nAlso, we should document why we use a different branch and why it's good. I'll try to explain here:\r\n\r\nOver time, the user may change the value of the `revision` attribute from one branch to another, or to a tag, or a specific commit SHA, and back. The user might even point set the revision attribute to a branch where history gets rewritten. So rather that just track a specific branch or do a \"headless\" checkout of a commit, the git provider maintains its own branch (which should be a branch that does NOT exist on your upstream repo). The provider is then free to forcibly checkout this branch to any commit, without screwing up the local history of an existing branch (e.g., master), which could cause problems or confusion later. The fact that the branch on the box is named \"deploy\" is pretty much irrelevant; if you use `git rev-parse` and `git ls-remote`, you will see that chef is syncing your code to exactly the right commit."},"comment":{"url":"https://api.github.com/repos/chef/chef-docs/issues/comments/114642765","html_url":"https://github.com/chef/chef-docs/issues/552#issuecomment-114642765","issue_url":"https://api.github.com/repos/chef/chef-docs/issues/552","id":114642765,"user":{"login":"iankronquist","id":5192353,"avatar_url":"https://avatars.githubusercontent.com/u/5192353?v=3","gravatar_id":"","url":"https://api.github.com/users/iankronquist","html_url":"https://github.com/iankronquist","followers_url":"https://api.github.com/users/iankronquist/followers","following_url":"https://api.github.com/users/iankronquist/following{/other_user}","gists_url":"https://api.github.com/users/iankronquist/gists{/gist_id}","starred_url":"https://api.github.com/users/iankronquist/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/iankronquist/subscriptions","organizations_url":"https://api.github.com/users/iankronquist/orgs","repos_url":"https://api.github.com/users/iankronquist/repos","events_url":"https://api.github.com/users/iankronquist/events{/privacy}","received_events_url":"https://api.github.com/users/iankronquist/received_events","type":"User","site_admin":false},"created_at":"2015-06-23T21:10:53Z","updated_at":"2015-06-23T21:10:53Z","body":"@danielsdeleo Thanks! I think that will help rectify a lot of people's confusion."}}