{"action":"created","comment":{"url":"https://api.github.com/repos/docker/docker/pulls/comments/26544989","id":26544989,"diff_hunk":"@@ -1832,8 +1837,39 @@ An example of a file passed with `--env-file`\n \n     $ sudo docker run --name console -t -i ubuntu bash\n \n-This will create and run a new container with the container name being\n-`console`.\n+A label is a a `key=value` pair that applies metadata to a container. To label a container with two labels:\n+\n+    $ sudo docker run -l my-label --label com.example.foo=bar ubuntu bash\n+\n+The `my-label` key doesn't specify so the label defaults to an empty\n+string(`\"\"`). To add multiple labels, repeat the label flag (`-l` or\n+`--label`).\n+\n+The `key=value` must be unique. If you specify the same key multiple times\n+with different values, each subsequent value overwrites the previous. Docker\n+applies the last `key=value` you supply.\n+\n+Use the `--label-file` flag to load multiple labels from a file. Delimit each\n+label in the file with an EOL mark. The example below loads labels from a\n+labels file in the current directory;\n+\n+    $ sudo docker run --label-file ./labels ubuntu bash\n+\n+The label-file format is similar to the format for loading environment variables\n+(see `--env-file` above). The following example illustrates a label-file format;","path":"docs/sources/reference/commandline/cli.md","position":51,"original_position":51,"commit_id":"fae92d5f0a1d81a48dc210d5ae28ef83c724b5ac","original_commit_id":"fae92d5f0a1d81a48dc210d5ae28ef83c724b5ac","user":{"login":"SvenDowideit","id":28492,"avatar_url":"https://avatars.githubusercontent.com/u/28492?v=3","gravatar_id":"","url":"https://api.github.com/users/SvenDowideit","html_url":"https://github.com/SvenDowideit","followers_url":"https://api.github.com/users/SvenDowideit/followers","following_url":"https://api.github.com/users/SvenDowideit/following{/other_user}","gists_url":"https://api.github.com/users/SvenDowideit/gists{/gist_id}","starred_url":"https://api.github.com/users/SvenDowideit/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/SvenDowideit/subscriptions","organizations_url":"https://api.github.com/users/SvenDowideit/orgs","repos_url":"https://api.github.com/users/SvenDowideit/repos","events_url":"https://api.github.com/users/SvenDowideit/events{/privacy}","received_events_url":"https://api.github.com/users/SvenDowideit/received_events","type":"User","site_admin":false},"body":"can this be a link?","created_at":"2015-03-17T02:19:17Z","updated_at":"2015-03-17T02:19:17Z","html_url":"https://github.com/docker/docker/pull/9882#discussion_r26544989","pull_request_url":"https://api.github.com/repos/docker/docker/pulls/9882","_links":{"self":{"href":"https://api.github.com/repos/docker/docker/pulls/comments/26544989"},"html":{"href":"https://github.com/docker/docker/pull/9882#discussion_r26544989"},"pull_request":{"href":"https://api.github.com/repos/docker/docker/pulls/9882"}}},"pull_request":{"url":"https://api.github.com/repos/docker/docker/pulls/9882","id":26780049,"html_url":"https://github.com/docker/docker/pull/9882","diff_url":"https://github.com/docker/docker/pull/9882.diff","patch_url":"https://github.com/docker/docker/pull/9882.patch","issue_url":"https://api.github.com/repos/docker/docker/issues/9882","number":9882,"state":"open","locked":false,"title":"Proposal: One Meta Data to Rule Them All => Labels","user":{"login":"ibuildthecloud","id":1754002,"avatar_url":"https://avatars.githubusercontent.com/u/1754002?v=3","gravatar_id":"","url":"https://api.github.com/users/ibuildthecloud","html_url":"https://github.com/ibuildthecloud","followers_url":"https://api.github.com/users/ibuildthecloud/followers","following_url":"https://api.github.com/users/ibuildthecloud/following{/other_user}","gists_url":"https://api.github.com/users/ibuildthecloud/gists{/gist_id}","starred_url":"https://api.github.com/users/ibuildthecloud/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ibuildthecloud/subscriptions","organizations_url":"https://api.github.com/users/ibuildthecloud/orgs","repos_url":"https://api.github.com/users/ibuildthecloud/repos","events_url":"https://api.github.com/users/ibuildthecloud/events{/privacy}","received_events_url":"https://api.github.com/users/ibuildthecloud/received_events","type":"User","site_admin":false},"body":"This is yet another meta data PR in an attempt to [pull together](http://xkcd.com/927/) multiple PRs hopefully into something we can get into Docker 1.5 (seriously, let's move fast).\r\n\r\n## Background\r\nSome background... (from what I can gather).  There is currently https://github.com/docker/docker/pull/8955 for adding UserData to a Dockerfile.  Basically it adds the `USERDATA key=value key=\"long value\"` syntax to the Docker.  Then there is https://github.com/docker/docker/pull/9013 which looks to add structured JSON data to a Dockerfile and a container in much the same fashion as Kubernete's annotations.  Finally there is https://github.com/docker/docker/pull/9854 which discusses the need for meta data on container to help with Swarm and similar clustering systems.  There are probably another 10 threads that @thaJeztah can find that also talk about the need to add meta data to containers.\r\n\r\n## We need this...\r\nWe need meta data, it's clear user want it.\r\n\r\n## Labels\r\n\r\nWe already have labels on Hosts (Docker daemon) today.  It seems that going forward we should be able to add labels to everything: Hosts, containers, volumes, images, etc.  Let's just continue with that approach.  Labels are simple key/value pairs in the style of `map[string]string`.  There have been comments to standarize the format of the keys such that we have namespaces or other means to prevent conflicts.  Honestly I don't think that is all that necesary at the Docker level to dictate this.  It's just good practice to namespace things.  Whether you do \"foo_bar\" or \"foo/bar\" or \"com.foo/bar\", who really cares.  If your going to use \"id=3\", well that's a bad name and somebody may clobber your value.  I'm assuming some will disagree with me on this one.  That's fine, I'll agree to a namespace standard just as long as it doesn't take three weeks and 132 comments to decide that DNS format is far superior to arbitrary strings split by \"/\".\r\n\r\nLabels are not structured data, and as such this PR is different from https://github.com/docker/docker/pull/9013, so that discussion can happen differently.  Honestly, I'm not in favor of adding structured data to objects and having Docker maintain it.  But if others disagree, so be it, we can have structured data as something else.\r\n\r\n## What about ENV vars\r\n\r\nYes, labels are very close to environment variables.  You can add ENV to a Dockerfile and you can add them at container create.  The basic difference here is that these key/values are not visible to the running processes in the container.\r\n\r\n## Lookup by Label\r\n\r\nAnother key attribute of labels is that you should be able to find an object based on it's label.  This should initially be kept very simple.  You can either say \"give me all images/containers that have key foo.\"  Or you can say \"give me all images/containers that have foo=bar\".\r\n\r\n## How should we go about doing this?\r\n\r\nI think https://github.com/docker/docker/pull/8955 is the right start.  `USERDATA` should be renamed to `LABEL`.  Now that we have `LABEL` on images we need to add `--label key=value` to `docker run/create`.  This is in the same fashion as `ENV` and `-e` today.\r\n\r\nNow the only thing left do to is to figure out how to query based on labels.  We just need to add `--label foo` or `--label foo=bar` to `docker images/ps`.\r\n\r\n## It's just that simple folks\r\n\r\nOkay, good?  Alright, let's move forward...","created_at":"2015-01-03T06:18:06Z","updated_at":"2015-03-17T02:19:17Z","closed_at":null,"merged_at":null,"merge_commit_sha":"ef932f756a674edb02170e266e4edd8989d7ecee","assignee":{"login":"icecrime","id":1564054,"avatar_url":"https://avatars.githubusercontent.com/u/1564054?v=3","gravatar_id":"","url":"https://api.github.com/users/icecrime","html_url":"https://github.com/icecrime","followers_url":"https://api.github.com/users/icecrime/followers","following_url":"https://api.github.com/users/icecrime/following{/other_user}","gists_url":"https://api.github.com/users/icecrime/gists{/gist_id}","starred_url":"https://api.github.com/users/icecrime/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/icecrime/subscriptions","organizations_url":"https://api.github.com/users/icecrime/orgs","repos_url":"https://api.github.com/users/icecrime/repos","events_url":"https://api.github.com/users/icecrime/events{/privacy}","received_events_url":"https://api.github.com/users/icecrime/received_events","type":"User","site_admin":false},"milestone":{"url":"https://api.github.com/repos/docker/docker/milestones/37","html_url":"https://github.com/docker/docker/milestones/1.6.0","labels_url":"https://api.github.com/repos/docker/docker/milestones/37/labels","id":952335,"number":37,"title":"1.6.0","description":"","creator":{"login":"crosbymichael","id":749551,"avatar_url":"https://avatars.githubusercontent.com/u/749551?v=3","gravatar_id":"","url":"https://api.github.com/users/crosbymichael","html_url":"https://github.com/crosbymichael","followers_url":"https://api.github.com/users/crosbymichael/followers","following_url":"https://api.github.com/users/crosbymichael/following{/other_user}","gists_url":"https://api.github.com/users/crosbymichael/gists{/gist_id}","starred_url":"https://api.github.com/users/crosbymichael/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/crosbymichael/subscriptions","organizations_url":"https://api.github.com/users/crosbymichael/orgs","repos_url":"https://api.github.com/users/crosbymichael/repos","events_url":"https://api.github.com/users/crosbymichael/events{/privacy}","received_events_url":"https://api.github.com/users/crosbymichael/received_events","type":"User","site_admin":false},"open_issues":33,"closed_issues":37,"state":"open","created_at":"2015-01-26T23:40:13Z","updated_at":"2015-03-17T01:09:13Z","due_on":"2015-03-23T07:00:00Z","closed_at":null},"commits_url":"https://api.github.com/repos/docker/docker/pulls/9882/commits","review_comments_url":"https://api.github.com/repos/docker/docker/pulls/9882/comments","review_comment_url":"https://api.github.com/repos/docker/docker/pulls/comments{/number}","comments_url":"https://api.github.com/repos/docker/docker/issues/9882/comments","statuses_url":"https://api.github.com/repos/docker/docker/statuses/fae92d5f0a1d81a48dc210d5ae28ef83c724b5ac","head":{"label":"ibuildthecloud:labels","ref":"labels","sha":"fae92d5f0a1d81a48dc210d5ae28ef83c724b5ac","user":{"login":"ibuildthecloud","id":1754002,"avatar_url":"https://avatars.githubusercontent.com/u/1754002?v=3","gravatar_id":"","url":"https://api.github.com/users/ibuildthecloud","html_url":"https://github.com/ibuildthecloud","followers_url":"https://api.github.com/users/ibuildthecloud/followers","following_url":"https://api.github.com/users/ibuildthecloud/following{/other_user}","gists_url":"https://api.github.com/users/ibuildthecloud/gists{/gist_id}","starred_url":"https://api.github.com/users/ibuildthecloud/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ibuildthecloud/subscriptions","organizations_url":"https://api.github.com/users/ibuildthecloud/orgs","repos_url":"https://api.github.com/users/ibuildthecloud/repos","events_url":"https://api.github.com/users/ibuildthecloud/events{/privacy}","received_events_url":"https://api.github.com/users/ibuildthecloud/received_events","type":"User","site_admin":false},"repo":{"id":16563024,"name":"docker","full_name":"ibuildthecloud/docker","owner":{"login":"ibuildthecloud","id":1754002,"avatar_url":"https://avatars.githubusercontent.com/u/1754002?v=3","gravatar_id":"","url":"https://api.github.com/users/ibuildthecloud","html_url":"https://github.com/ibuildthecloud","followers_url":"https://api.github.com/users/ibuildthecloud/followers","following_url":"https://api.github.com/users/ibuildthecloud/following{/other_user}","gists_url":"https://api.github.com/users/ibuildthecloud/gists{/gist_id}","starred_url":"https://api.github.com/users/ibuildthecloud/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ibuildthecloud/subscriptions","organizations_url":"https://api.github.com/users/ibuildthecloud/orgs","repos_url":"https://api.github.com/users/ibuildthecloud/repos","events_url":"https://api.github.com/users/ibuildthecloud/events{/privacy}","received_events_url":"https://api.github.com/users/ibuildthecloud/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/ibuildthecloud/docker","description":"Docker - the open-source application container engine","fork":true,"url":"https://api.github.com/repos/ibuildthecloud/docker","forks_url":"https://api.github.com/repos/ibuildthecloud/docker/forks","keys_url":"https://api.github.com/repos/ibuildthecloud/docker/keys{/key_id}","collaborators_url":"https://api.github.com/repos/ibuildthecloud/docker/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/ibuildthecloud/docker/teams","hooks_url":"https://api.github.com/repos/ibuildthecloud/docker/hooks","issue_events_url":"https://api.github.com/repos/ibuildthecloud/docker/issues/events{/number}","events_url":"https://api.github.com/repos/ibuildthecloud/docker/events","assignees_url":"https://api.github.com/repos/ibuildthecloud/docker/assignees{/user}","branches_url":"https://api.github.com/repos/ibuildthecloud/docker/branches{/branch}","tags_url":"https://api.github.com/repos/ibuildthecloud/docker/tags","blobs_url":"https://api.github.com/repos/ibuildthecloud/docker/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/ibuildthecloud/docker/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/ibuildthecloud/docker/git/refs{/sha}","trees_url":"https://api.github.com/repos/ibuildthecloud/docker/git/trees{/sha}","statuses_url":"https://api.github.com/repos/ibuildthecloud/docker/statuses/{sha}","languages_url":"https://api.github.com/repos/ibuildthecloud/docker/languages","stargazers_url":"https://api.github.com/repos/ibuildthecloud/docker/stargazers","contributors_url":"https://api.github.com/repos/ibuildthecloud/docker/contributors","subscribers_url":"https://api.github.com/repos/ibuildthecloud/docker/subscribers","subscription_url":"https://api.github.com/repos/ibuildthecloud/docker/subscription","commits_url":"https://api.github.com/repos/ibuildthecloud/docker/commits{/sha}","git_commits_url":"https://api.github.com/repos/ibuildthecloud/docker/git/commits{/sha}","comments_url":"https://api.github.com/repos/ibuildthecloud/docker/comments{/number}","issue_comment_url":"https://api.github.com/repos/ibuildthecloud/docker/issues/comments{/number}","contents_url":"https://api.github.com/repos/ibuildthecloud/docker/contents/{+path}","compare_url":"https://api.github.com/repos/ibuildthecloud/docker/compare/{base}...{head}","merges_url":"https://api.github.com/repos/ibuildthecloud/docker/merges","archive_url":"https://api.github.com/repos/ibuildthecloud/docker/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/ibuildthecloud/docker/downloads","issues_url":"https://api.github.com/repos/ibuildthecloud/docker/issues{/number}","pulls_url":"https://api.github.com/repos/ibuildthecloud/docker/pulls{/number}","milestones_url":"https://api.github.com/repos/ibuildthecloud/docker/milestones{/number}","notifications_url":"https://api.github.com/repos/ibuildthecloud/docker/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/ibuildthecloud/docker/labels{/name}","releases_url":"https://api.github.com/repos/ibuildthecloud/docker/releases{/id}","created_at":"2014-02-05T23:52:41Z","updated_at":"2014-07-24T21:22:38Z","pushed_at":"2015-03-17T00:08:49Z","git_url":"git://github.com/ibuildthecloud/docker.git","ssh_url":"git@github.com:ibuildthecloud/docker.git","clone_url":"https://github.com/ibuildthecloud/docker.git","svn_url":"https://github.com/ibuildthecloud/docker","homepage":"http://www.docker.io","size":44893,"stargazers_count":0,"watchers_count":0,"language":"Go","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":1,"forks":0,"open_issues":1,"watchers":0,"default_branch":"master"}},"base":{"label":"docker:master","ref":"master","sha":"87a8658eb625d25d4d72bf65efc5629be4c99d40","user":{"login":"docker","id":5429470,"avatar_url":"https://avatars.githubusercontent.com/u/5429470?v=3","gravatar_id":"","url":"https://api.github.com/users/docker","html_url":"https://github.com/docker","followers_url":"https://api.github.com/users/docker/followers","following_url":"https://api.github.com/users/docker/following{/other_user}","gists_url":"https://api.github.com/users/docker/gists{/gist_id}","starred_url":"https://api.github.com/users/docker/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/docker/subscriptions","organizations_url":"https://api.github.com/users/docker/orgs","repos_url":"https://api.github.com/users/docker/repos","events_url":"https://api.github.com/users/docker/events{/privacy}","received_events_url":"https://api.github.com/users/docker/received_events","type":"Organization","site_admin":false},"repo":{"id":7691631,"name":"docker","full_name":"docker/docker","owner":{"login":"docker","id":5429470,"avatar_url":"https://avatars.githubusercontent.com/u/5429470?v=3","gravatar_id":"","url":"https://api.github.com/users/docker","html_url":"https://github.com/docker","followers_url":"https://api.github.com/users/docker/followers","following_url":"https://api.github.com/users/docker/following{/other_user}","gists_url":"https://api.github.com/users/docker/gists{/gist_id}","starred_url":"https://api.github.com/users/docker/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/docker/subscriptions","organizations_url":"https://api.github.com/users/docker/orgs","repos_url":"https://api.github.com/users/docker/repos","events_url":"https://api.github.com/users/docker/events{/privacy}","received_events_url":"https://api.github.com/users/docker/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/docker/docker","description":"Docker - the open-source application container engine","fork":false,"url":"https://api.github.com/repos/docker/docker","forks_url":"https://api.github.com/repos/docker/docker/forks","keys_url":"https://api.github.com/repos/docker/docker/keys{/key_id}","collaborators_url":"https://api.github.com/repos/docker/docker/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/docker/docker/teams","hooks_url":"https://api.github.com/repos/docker/docker/hooks","issue_events_url":"https://api.github.com/repos/docker/docker/issues/events{/number}","events_url":"https://api.github.com/repos/docker/docker/events","assignees_url":"https://api.github.com/repos/docker/docker/assignees{/user}","branches_url":"https://api.github.com/repos/docker/docker/branches{/branch}","tags_url":"https://api.github.com/repos/docker/docker/tags","blobs_url":"https://api.github.com/repos/docker/docker/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/docker/docker/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/docker/docker/git/refs{/sha}","trees_url":"https://api.github.com/repos/docker/docker/git/trees{/sha}","statuses_url":"https://api.github.com/repos/docker/docker/statuses/{sha}","languages_url":"https://api.github.com/repos/docker/docker/languages","stargazers_url":"https://api.github.com/repos/docker/docker/stargazers","contributors_url":"https://api.github.com/repos/docker/docker/contributors","subscribers_url":"https://api.github.com/repos/docker/docker/subscribers","subscription_url":"https://api.github.com/repos/docker/docker/subscription","commits_url":"https://api.github.com/repos/docker/docker/commits{/sha}","git_commits_url":"https://api.github.com/repos/docker/docker/git/commits{/sha}","comments_url":"https://api.github.com/repos/docker/docker/comments{/number}","issue_comment_url":"https://api.github.com/repos/docker/docker/issues/comments{/number}","contents_url":"https://api.github.com/repos/docker/docker/contents/{+path}","compare_url":"https://api.github.com/repos/docker/docker/compare/{base}...{head}","merges_url":"https://api.github.com/repos/docker/docker/merges","archive_url":"https://api.github.com/repos/docker/docker/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/docker/docker/downloads","issues_url":"https://api.github.com/repos/docker/docker/issues{/number}","pulls_url":"https://api.github.com/repos/docker/docker/pulls{/number}","milestones_url":"https://api.github.com/repos/docker/docker/milestones{/number}","notifications_url":"https://api.github.com/repos/docker/docker/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/docker/docker/labels{/name}","releases_url":"https://api.github.com/repos/docker/docker/releases{/id}","created_at":"2013-01-18T18:10:57Z","updated_at":"2015-03-17T02:13:20Z","pushed_at":"2015-03-17T01:21:12Z","git_url":"git://github.com/docker/docker.git","ssh_url":"git@github.com:docker/docker.git","clone_url":"https://github.com/docker/docker.git","svn_url":"https://github.com/docker/docker","homepage":"http://www.docker.com","size":153246,"stargazers_count":19880,"watchers_count":19880,"language":"Go","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":4159,"mirror_url":null,"open_issues_count":807,"forks":4159,"open_issues":807,"watchers":19880,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/docker/docker/pulls/9882"},"html":{"href":"https://github.com/docker/docker/pull/9882"},"issue":{"href":"https://api.github.com/repos/docker/docker/issues/9882"},"comments":{"href":"https://api.github.com/repos/docker/docker/issues/9882/comments"},"review_comments":{"href":"https://api.github.com/repos/docker/docker/pulls/9882/comments"},"review_comment":{"href":"https://api.github.com/repos/docker/docker/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/docker/docker/pulls/9882/commits"},"statuses":{"href":"https://api.github.com/repos/docker/docker/statuses/fae92d5f0a1d81a48dc210d5ae28ef83c724b5ac"}}}}