github.com/comcast/canticle@v0.0.0-20161108184242-c53cface56e8/website/docs.html (about) 1 <!DOCTYPE html> 2 <html lang="en"> 3 <head> 4 <meta charset="utf-8"> 5 <meta http-equiv="X-UA-Compatible" content="IE=edge"> 6 <meta name="viewport" content="width=device-width, initial-scale=1"> 7 <!-- The above 3 meta tags *must* come first in the head; any other head content must come *after* these tags --> 8 <meta name="description" content=""> 9 <meta name="author" content=""> 10 <link rel="icon" href="favicon.ico"> 11 12 <title>Canticle</title> 13 14 <!-- Bootstrap core CSS --> 15 <link rel="stylesheet" href="http://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap.min.css"> 16 <script src="http://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/js/ie-emulation-modes-warning.js"></script> 17 18 <!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries --> 19 <!--[if lt IE 9]> 20 <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script> 21 <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script> 22 <![endif]--> 23 24 <!-- Custom styles for this template --> 25 <link href="carousel.css" rel="stylesheet"> 26 </head> 27 <!-- NAVBAR 28 ================================================== --> 29 <body> 30 <nav class="navbar navbar-inverse navbar-fixed-top"> 31 <div class="container"> 32 <div class="navbar-header"> 33 <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false" aria-controls="navbar"> 34 <span class="sr-only">Toggle navigation</span> 35 <span class="icon-bar"></span> 36 <span class="icon-bar"></span> 37 <span class="icon-bar"></span> 38 </button> 39 <a class="navbar-brand" href="index.html"><img height="40" src="cant.png" /></a> 40 </div> 41 <div id="navbar" class="navbar-collapse collapse"> 42 <ul class="nav navbar-nav"> 43 <li><a href="index.html">Home</a></li> 44 <li><a href="about.html">About</a></li> 45 <li class="dropdown"> 46 <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Quick Start Guides<span class="caret"></span></a> 47 <ul class="dropdown-menu"> 48 <li><a href="quickstart.html#library">Library</a></li> 49 <li><a href="quickstart.html#project">Project</a></li> 50 <li><a href="quickstart.html#workspace">Workspace</a></li> 51 </ul> 52 </li> 53 <li class="active dropdown"> 54 <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Docs<span class="caret"></span></a> 55 <ul class="dropdown-menu"> 56 <li class="dropdown-header">Canticle</li> 57 <li><a href="docs.html#cant"><code>cant</code></a></li> 58 <li role="separator" class="divider"></li> 59 <li class="dropdown-header">Commands</li> 60 <li><a href="docs.html#cantget"><code>cant get</code></a></li> 61 <li><a href="docs.html#cantsave"><code>cant save</code></a></li> 62 <li><a href="docs.html#cantvendor"><code>cant vendor</code></a></li> 63 <li><a href="docs.html#cantgenversion"><code>cant genversion</code></a></li> 64 <li role="separator" class="divider"></li> 65 <li class="dropdown-header">Internals</li> 66 <li><a href="docs.html#canticlefile">Canticle Files</a></li> 67 <li><a href="docs.html#vcs">VCS Commands</a></li> 68 </ul> 69 </li> 70 </ul> 71 <ul class="nav navbar-nav pull-right"> 72 <li class="icon-bar"><a title="sauce" href="http://github.com/Comcast/Canticle"><img src="https://assets.github.com/images/icons/emoji/octocat.png" /></a></li> 73 <li class="icon-bar"><a title="sauce" href="http://careers.stackoverflow.com/company/comcast-viper"><img src="ComcastFrog-VIPER-black.svg" /></a></li> 74 </ul> 75 </div> 76 </div> 77 </nav> <!-- /navbar --> 78 79 80 <!-- Marketing messaging and featurettes 81 ================================================== --> 82 <!-- Wrap the rest of the page in another container to center all the content. --> 83 84 <div class="container marketing"> 85 <div> 86 <h1 id="cant"><code>cant</code></h> 87 <h2>Description</h2> 88 <p>The cant command wraps the <a href="#commands">commands</a> 89 below. They are issued as <code>cant get</code>, <code>cant 90 save</code>, <code>cant vendor</code>, and <code>cant 91 genversion</code>.</p> 92 <h2>Options</h2> 93 <ul> 94 <li><code>-version</code> Print the version information for Canticle.</li> 95 <li><code>-h</code> Print the help for this command.</p></li> 96 </ul> 97 </div> 98 99 <hr class="featurette-divider"> 100 <div id="commands"> 101 <h1 id="cantget"><code>get</code></h1> 102 <h2>Description</h2> 103 <p>The get command fetches the items in the Canticle file, and 104 sets them to the revisions in the Canticle 105 file. If <code>-u</code> is specified the get command will 106 attempt to update any branches to the latest remote version.</p> 107 <p>Fetches are performed in parallel with get. Get will report 108 any failures fetching or updating the listed 109 projects. However, it will not halt on errors. Rather it 110 reports them after all items in the Canticle file have been 111 fetched or updated.</p> 112 <p>Get fetches items from the <code>SourcePath</code> 113 attributed of the Canticle file into the <code>Root</code> 114 specified by that item. If a revision is set it will attempt 115 to set the repo to that revision, branch, or tag. If no 116 sourcepath is specified it will attempt to use the same 117 discovery mechanisms as <code>go get</code> to fetch the 118 project. If no revision is specified the default branch 119 (master for git) will be used.</p> 120 <h2>Options</h2> 121 <ul> 122 <li><code>-u</code> Attempt to update any branch to the latest remote version. Only non-destructive updates will be performed.</li> 123 <li><code>-v</code> Print a verbose set of operations preformed.</li> 124 <li><code>-h</code> Print the help for this command.</p></li> 125 </ul> 126 </div> 127 128 <hr class="featurette-divider"> 129 <div> 130 <h1 id="cantsave"><code>save</code></h1> 131 <h2>Description</h2> 132 <p>Save walks the dependency graph and file tree for packages 133 at and below where it is issued. When you run save in a directory, 134 all packages in folders underneath that directory are searched. 135 Folders with no buildable go sources are ignored. The dependency 136 graph is then searched. The result of save is a set of version 137 control system (VCS) roots.</p> 138 <p>If <code>-exclude <dir></code> is issued, save will 139 not walk into this directory or it subdirectories when 140 walking the file hierarchy. However, if a package is imported 141 from another directory, it will still be included.</p> 142 <p>Canticle examines the sources and revisions of each VCS 143 system on disk. If other Canticle files appear in the search 144 path, these may result in conflicts. By default save will 145 prompt the user to choose a version. If <code>-ondisk</code> 146 is added, it will use the revisions currently on disk. Note: 147 setting a revision in save <i>does not</i> update it. To do 148 this you must issue get.</p> 149 <p>Save uses an exact commit to save (git commit hash, svn 150 revision, hg commit id, bzr revision). A preference for 151 named branches or tags can be specified 152 with <code>-b</code>. In git these are any refs 153 under <code>refs/heads/</code> 154 or <code>refs/remotes/</code>. The branches feature is 155 currently not implemented for other VCS but is planned. </p> 156 <h2>Options</h2> 157 <ul> 158 <li><code>-d</code> Print the generated Canticle file, don't save it.</li> 159 <li><code>-b</code> Prefer branches for revisions in the generated Canticle file.</li> 160 <li><code>-ondisk</code> Use the revisions and sources currently on disk.</li> 161 <li><code>-no-sources</code> Do not save the source url of VCS repos. Useful for library maintainers.</li> 162 <li><code>-v</code> Print a verbose set of operations performed.</li> 163 <li><code>-h</code> Print the help for this command.</p></li> 164 </ul> 165 </div> 166 167 <hr class="featurette-divider"> 168 <div> 169 <h1 id="cantvendor"><code>vendor</code></h1> 170 <h2>Description</h2> 171 <p>Vendor fetches a dependency and all of its 172 dependencies. They are placed into the workspace in the same 173 manner as <code>go get</code>. Dependencies already on disk 174 will not be overwritten. Use save and then get to force the 175 checkout of the appropriate versions for the vendored 176 item.</p> 177 <p>Vendor can take an input Canticle file to force certain 178 dependencies to come from other sources and revisions. 179 This is the <code>-s</code> option.</p> 180 <h2>Options</h2> 181 <ul> 182 <li><code>-s</code> Use the specified Canticle file to override the source(s) of fetched libraries.</li> 183 <li><code>-v</code> Print a verbose set of operations performed.</li> 184 <li><code>-h</code> Print the help for this command.</p></li> 185 </ul> 186 </div> 187 188 <hr class="featurette-divider"> 189 <div> 190 <h1 id="genversion"><code>genversion</code></h1> 191 <h2>Description</h2> 192 <p>Genversion generates build time version information for 193 inclusion with your project. This is important for dynamic 194 workspaces (such as being tied to masters). This allows code 195 bases to be both reproducible and continuously released.</p> 196 <p>Genversion does not require a link dependency on 197 Canticle. The generated version information will be entirely 198 contained in the buildinfo package. This is also type safe 199 information.</p> 200 <h2>Usage</h2> 201 <p>The <a href="">Canticle main file</a> has a good example of usage. In short you must: 202 <ul> 203 <li>Call genversion.</li> 204 <li>Check in the buildinfo/info.go file that is generated, but <i>not</i> buildinfo.go.</li> 205 <li>Import the buildinfo package.</li> 206 <li>Use <code>buildinfo.GetBuildInfo()</code></li> 207 </ul> 208 The buildinfo will contain BuildTime, User, Host, and the 209 local repo Revision. It also includes CanticleDeps which is 210 a <code>*json.RawMessage</code> to prevent adding types. 211 </p> 212 </div> 213 <!-- FOOTER --> 214 <footer> 215 <p class="pull-right"><a href="#">Back to top</a></p> 216 </footer> 217 218 </div><!-- /.container --> 219 220 221 <!-- Bootstrap core JavaScript 222 ================================================== --> 223 <!-- Placed at the end of the document so the pages load faster --> 224 <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script> 225 <script src="http://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/js/bootstrap.min.js"></script> 226 <!-- Just to make our placeholder images work. Don't actually copy the next line! --> 227 <!-- IE10 viewport hack for Surface/desktop Windows 8 bug --> 228 <script src="http://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/js/ie10-viewport-bug-workaround.js"></script> 229 </body> 230 </html>