PageSourceSearch

https://pkg.go.dev/about

html go.dev collected 2026-10-01 06:46:15 UTC 43,380 bytes, 984 lines download raw bytes

1
2
3<!DOCTYPE html>
4<html lang="en" data-layout="" data-local="">
5  <head>
6    
7    
7<script>
8      window.addEventListener('error', window.__err=function f(e){f.p=f.p||[];f.p.push(e)});
9    </script>
9
10    
10<script>
11      (function() {
12        const theme = document.cookie.match(/prefers-color-scheme=(light|dark|auto)/)?.[1]
13        if (theme) {
14          document.querySelector('html').setAttribute('data-theme', theme);
15        }
16      }())
17    </script>
17
18    <meta charset="utf-8">
19    <meta http-equiv="X-UA-Compatible" content="IE=edge">
20    <meta name="viewport" content="width=device-width, initial-scale=1.0">
21    
22      <meta name="description" content="Go is an open source programming language that makes it easy to build simple, reliable, and efficient software.">
23    
24    
25    <meta class="js-gtmID" data-gtmid="GTM-W8MVQXG">
26    <link rel="shortcut icon" href="/static/shared/icon/favicon.ico">
27    
28    <link href="/static/frontend/frontend.min.css?version=prod-frontend-00257-ksj" rel="stylesheet">
29    
30    <link rel="search" type="application/opensearchdescription+xml" href="/opensearch.xml" title="Go Packages">
31    
32    
33      <title>About - Go Packages</title>
34    
35    
36  <link href="/static/frontend/about/about.min.css?version=prod-frontend-00257-ksj" rel="stylesheet">
37
38  </head>
39  <body>
40    
41    
41<script>
42      function loadScript(src, mod = true) {
43        let s = document.createElement('script');
44        s.src = src;
45        if (mod) {
46          s.type = 'module';
47          s.async = true;
48          s.defer = true
49        }
50        document.head.appendChild(s);
51      }
52      loadScript("/third_party/dialog-polyfill/dialog-polyfill.js", false)
53      loadScript("/static/frontend/frontend.js");
54    </script>
54
55    
56  <header class="go-Header js-siteHeader">
57    <div class="go-Header-inner go-Header-inner--dark">
58      <nav class="go-Header-nav">
59        <a href="https://go.dev/" class="js-headerLogo" data-gtmc="nav link"
60            data-test-id="go-header-logo-link" role="heading" aria-level="1">
61          <img class="go-Header-logo" src="/static/shared/logo/go-white.svg" alt="Go">
62        </a>
63         <div class="skip-navigation-wrapper">
64            <a class="skip-to-content-link" aria-label="Skip to main content" href="#main-content"> Skip to Main Content </a>
65          </div>
66        <div class="go-Header-rightContent">
67          
68<div class="go-SearchForm js-searchForm">
69  <form
70    class="go-InputGroup go-ShortcutKey go-SearchForm-form"
71    action="/search"
72    data-shortcut="/"
73    data-shortcut-alt="search"
74    data-gtmc="search form"
75    aria-label="Search for a package"
76    role="search"
77  >
78    <input name="q" class="go-Input js-searchFocus" aria-label="Search for a package" type="search"
79        autocapitalize="off" autocomplete="off" autocorrect="off" spellcheck="false"
80        placeholder="Search packages or symbols"
81        value="" />
82    <input name="m" value="" hidden>
83    <button class="go-Button go-Button--inverted" aria-label="Submit search">
84      <img
85        class="go-Icon"
86        height="24"
87        width="24"
88        src="/static/shared/icon/search_gm_grey_24dp.svg"
89        alt=""
90      />
91    </button>
92  </form>
93  <button class="go-SearchForm-expandSearch js-expandSearch" data-gtmc="nav button"
94      aria-label="Open search" data-test-id="expand-search">
95    <img class="go-Icon go-Icon--inverted" height="24" width="24"
96        src="/static/shared/icon/search_gm_grey_24dp.svg" alt="">
97
98  </button>
99</div>
100
101          <ul class="go-Header-menu">
102            <li class="go-Header-menuItem">
103              <a class="js-desktop-menu-hover" href="#" data-gtmc="nav link">
104                Why Go
105                <img class="go-Icon" height="24" width="24" src="/static/shared/icon/arrow_drop_down_gm_grey_24dp.svg" alt="submenu dropdown icon">
106              </a>
107              <ul class="go-Header-submenu go-Header-submenu--why js-desktop-submenu-hover" aria-label="submenu">
108                  <li class="go-Header-submenuItem">
109                    <div>
110                      <a href="https://go.dev/solutions/case-studies">
111                        <span>Case Studies</span>
112                      </a>
113                    </div>
114                    <p>Common problems companies solve with Go</p>
115                  </li>
116                  <li class="go-Header-submenuItem">
117                    <div>
118                      <a href="https://go.dev/solutions/use-cases">
119                        <span>Use Cases</span>
120                      </a>
121                    </div>
122                    <p>Stories about how and why companies use Go</p>
123                  </li>
124                  <li class="go-Header-submenuItem">
125                    <div>
126                      <a href="https://go.dev/security/">
127                        <span>Security</span>
128                      </a>
129                    </div>
130                    <p>How Go can help keep you secure by default</p>
131                  </li>
132              </ul>
133            </li>
134            <li class="go-Header-menuItem">
135              <a href="https://go.dev/learn/" data-gtmc="nav link">Learn</a>
136            </li>
137            <li class="go-Header-menuItem">
138              <a class="js-desktop-menu-hover" href="#" data-gtmc="nav link">
139                Docs
140                <img class="go-Icon" height="24" width="24" src="/static/shared/icon/arrow_drop_down_gm_grey_24dp.svg" alt="submenu dropdown icon">
141              </a>
142              <ul class="go-Header-submenu go-Header-submenu--docs js-desktop-submenu-hover" aria-label="submenu">
143                <li class="go-Header-submenuItem">
144                  <div>
145                    <a href="https://go.dev/doc/effective_go">
146                      <span>Effective Go</span>
147                    </a>
148                  </div>
149                  <p>Tips for writing clear, performant, and idiomatic Go code</p>
150                </li>
151                <li class="go-Header-submenuItem">
152                  <div>
153                    <a href="https://go.dev/doc/">
154                      <span>Go User Manual</span>
155                    </a>
156                  </div>
157                  <p>A complete introduction to building software with Go</p>
158                </li>
159                <li class="go-Header-submenuItem">
160                  <div>
161                    <a href="https://pkg.go.dev/std">
162                      <span>Standard library</span>
163                    </a>
164                  </div>
165                  <p>Reference documentation for Go's standard library</p>
166                </li>
167                <li class="go-Header-submenuItem">
168                  <div>
169                    <a href="https://go.dev/doc/devel/release">
170                      <span>Release Notes</span>
171                    </a>
172                  </div>
173                  <p>Learn what's new in each Go release</p>
174                </li>
175                <li class="go-Header-submenuItem">
176                  <div>
177                    <a href="/api">
178                      <span>API</span>
179                    </a>
180                  </div>
181                  <p>Reference documentation for the pkg.go.dev API</p>
182                </li>
183              </ul>
184            </li>
185            <li class="go-Header-menuItem go-Header-menuItem--active">
186              <a href="/" data-gtmc="nav link">Packages</a>
187            </li>
188            <li class="go-Header-menuItem">
189              <a class="js-desktop-menu-hover" href="#" data-gtmc="nav link">
190                Community
191                <img class="go-Icon" height="24" width="24" src="/static/shared/icon/arrow_drop_down_gm_grey_24dp.svg" alt="submenu dropdown icon">
192              </a>
193              <ul class="go-Header-submenu go-Header-submenu--community js-desktop-submenu-hover" aria-label="submenu">
194                <li class="go-Header-submenuItem">
195                  <div>
196                    <a href="https://go.dev/talks/">
197                      <span>Recorded Talks</span>
198                    </a>
199                  </div>
200                  <p>Videos from prior events</p>
201                </li>
202                <li class="go-Header-submenuItem">
203                  <div>
204                    <a href="https://www.meetup.com/pro/go">
205                      <span>Meetups</span>
206                      <i class="material-icons">
207                        <img class="go-Icon" height="24" width="24"
208                            src="/static/shared/icon/launch_gm_grey_24dp.svg" alt="">
209                      </i>
210                    </a>
211                  </div>
212                  <p>Meet other local Go developers</p>
213                </li>
214                <li class="go-Header-submenuItem">
215                  <div>
216                    <a href="https://github.com/golang/go/wiki/Conferences">
217                      <span>Conferences</span>
218                      <i class="material-icons">
219                        <img class="go-Icon" height="24" width="24"
220                            src="/static/shared/icon/launch_gm_grey_24dp.svg" alt="">
221                      </i>
222                    </a>
223                  </div>
224                  <p>Learn and network with Go developers from around the world</p>
225                </li>
226                <li class="go-Header-submenuItem">
227                  <div>
228                    <a href="https://go.dev/blog">
229                      <span>Go blog</span>
230                    </a>
231                  </div>
232                  <p>The Go project's official blog.</p>
233                </li>
234                <li class="go-Header-submenuItem">
235                  <div>
236                    <a href="https://go.dev/help">
237                      <span>Go project</span>
238                    </a>
239                  </div>
240                  <p>Get help and stay informed from Go</p>
241                </li>
242                <li class="go-Header-submenuItem">
243                  <div>
244                    Get connected
245                  </div>
246                  <p></p>
247                  <div class="go-Header-socialIcons">
248                      <a
249                        class="go-Header-socialIcon"
250                        aria-label="Get connected with google-groups (Opens in new window)"
251                        title="Get connected with google-groups (Opens in new window)"
252                        href="https://groups.google.com/g/golang-nuts">
253                        <img src="/static/shared/logo/social/google-groups.svg" />
254                      </a>
255                      <a
256                        class="go-Header-socialIcon"
257                        aria-label="Get connected with github (Opens in new window)"
258                        title="Get connected with github (Opens in new window)"
259                        href="https://github.com/golang">
260                        <img src="/static/shared/logo/social/github.svg" />
261                      </a>
262                      <a
263                        class="go-Header-socialIcon"
264                        aria-label="Get connected with twitter (Opens in new window)"
265                        title="Get connected with twitter (Opens in new window)"
266                        href="https://twitter.com/golang">
267                        <img src="/static/shared/logo/social/twitter.svg" />
268                      </a>
269                      <a
270                        class="go-Header-socialIcon"
271                        aria-label="Get connected with reddit (Opens in new window)"
272                        title="Get connected with reddit (Opens in new window)"
273                        href="https://www.reddit.com/r/golang/">
274                        <img src="/static/shared/logo/social/reddit.svg" />
275                      </a>
276                      <a
277                        class="go-Header-socialIcon"
278                        aria-label="Get connected with slack (Opens in new window)"
279                        title="Get connected with slack (Opens in new window)"
280                        href="https://invite.slack.golangbridge.org/">
281                        <img src="/static/shared/logo/social/slack.svg" />
282                      </a>
283                      <a
284                        class="go-Header-socialIcon"
285                        aria-label="Get connected with stack-overflow (Opens in new window)"
286                        title=""
287                        href="https://stackoverflow.com/collectives/go">
288                        <img src="/static/shared/logo/social/stack-overflow.svg" />
289                      </a>
290                  </div>
291                </li>
292              </ul>
293            </li>
294          </ul>
295          <button class="go-Header-navOpen js-headerMenuButton go-Header-navOpen--white" data-gtmc="nav button" aria-label="Open navigation">
296          </button>
297        </div>
298      </nav>
299    </div>
300  </header>
301  <aside class="go-NavigationDrawer js-header">
302    <nav class="go-NavigationDrawer-nav">
303      <div class="go-NavigationDrawer-header">
304        <a href="https://go.dev/">
305          <img class="go-NavigationDrawer-logo" src="/static/shared/logo/go-blue.svg" alt="Go.">
306        </a>
307      </div>
308      <ul class="go-NavigationDrawer-list">
309          <li class="go-NavigationDrawer-listItem js-mobile-subnav-trigger go-NavigationDrawer-hasSubnav">
310            <a href="#">
311              <span>Why Go</span>
312              <i class="material-icons">
313                <img class="go-Icon" height="24" width="24"
314                  src="/static/shared/icon/navigate_next_gm_grey_24dp.svg" alt="">
315              </i>
316            </a>
317
318            <div class="go-NavigationDrawer go-NavigationDrawer-submenuItem">
319              <div class="go-NavigationDrawer-nav">
320                <div class="go-NavigationDrawer-header">
321                  <a href="#">
322                    <i class="material-icons">
323                      <img class="go-Icon" height="24" width="24"
324                        src="/static/shared/icon/navigate_before_gm_grey_24dp.svg" alt="">
325                      </i>
326                      Why Go
327                  </a>
328                </div>
329                <ul class="go-NavigationDrawer-list">
330                  <li class="go-NavigationDrawer-listItem">
331                    <a href="https://go.dev/solutions/case-studies">
332                      Case Studies
333                    </a>
334                  </li>
335                  <li class="go-NavigationDrawer-listItem">
336                    <a href="https://go.dev/solutions/use-cases">
337                      Use Cases
338                    </a>
339                  </li>
340                  <li class="go-NavigationDrawer-listItem">
341                    <a href="https://go.dev/security/">
342                      Security
343                    </a>
344                  </li>
345                </ul>
346              </div>
347            </div>
348          </li>
349          <li class="go-NavigationDrawer-listItem">
350            <a href="https://go.dev/learn/">Learn</a>
351          </li>
352          <li class="go-NavigationDrawer-listItem js-mobile-subnav-trigger go-NavigationDrawer-hasSubnav">
353            <a href="#">
354              <span>Docs</span>
355              <i class="material-icons">
356                <img class="go-Icon" height="24" width="24"
357                  src="/static/shared/icon/navigate_next_gm_grey_24dp.svg" alt="">
358              </i>
359            </a>
360
361            <div class="go-NavigationDrawer go-NavigationDrawer-submenuItem">
362              <div class="go-NavigationDrawer-nav">
363                <div class="go-NavigationDrawer-header">
364                  <a href="#"><i class="material-icons">
365                    <img class="go-Icon" height="24" width="24"
366                      src="/static/shared/icon/navigate_before_gm_grey_24dp.svg" alt="">
367                    </i>
368                    Docs
369                  </a>
370                </div>
371                <ul class="go-NavigationDrawer-list">
372                  <li class="go-NavigationDrawer-listItem">
373                    <a href="https://go.dev/doc/effective_go">
374                      Effective Go
375                    </a>
376                  </li>
377                  <li class="go-NavigationDrawer-listItem">
378                    <a href="https://go.dev/doc/">
379                      Go User Manual
380                    </a>
381                  </li>
382                  <li class="go-NavigationDrawer-listItem">
383                    <a href="https://pkg.go.dev/std">
384                      Standard library
385                    </a>
386                  </li>
387                  <li class="go-NavigationDrawer-listItem">
388                    <a href="https://go.dev/doc/devel/release">
389                      Release Notes
390                    </a>
391                  </li>
392                  <li class="go-NavigationDrawer-listItem">
393                    <a href="/api">
394                      API
395                    </a>
396                  </li>
397                </ul>
398              </div>
399            </div>
400          </li>
401          <li class="go-NavigationDrawer-listItem go-NavigationDrawer-listItem--active">
402            <a href="/">Packages</a>
403          </li>
404          <li class="go-NavigationDrawer-listItem js-mobile-subnav-trigger go-NavigationDrawer-hasSubnav">
405            <a href="#">
406              <span>Community</span>
407              <i class="material-icons">
408                <img class="go-Icon" height="24" width="24"
409                  src="/static/shared/icon/navigate_next_gm_grey_24dp.svg" alt="">
410              </i>
411            </a>
412            <div class="go-NavigationDrawer go-NavigationDrawer-submenuItem">
413              <div class="go-NavigationDrawer-nav">
414                <div class="go-NavigationDrawer-header">
415                  <a href="#">
416                    <i class="material-icons">
417                      <img class="go-Icon" height="24" width="24"
418                        src="/static/shared/icon/navigate_before_gm_grey_24dp.svg" alt="">
419                    </i>
420                    Community
421                  </a>
422                </div>
423                <ul class="go-NavigationDrawer-list">
424                  <li class="go-NavigationDrawer-listItem">
425                    <a href="https://go.dev/talks/">
426                      Recorded Talks
427                    </a>
428                  </li>
429                  <li class="go-NavigationDrawer-listItem">
430                    <a href="https://www.meetup.com/pro/go">
431                      Meetups
432                      <i class="material-icons">
433                      <img class="go-Icon" height="24" width="24"
434                          src="/static/shared/icon/launch_gm_grey_24dp.svg" alt="">
435                      </i>
436                    </a>
437                  </li>
438                  <li class="go-NavigationDrawer-listItem">
439                    <a href="https://github.com/golang/go/wiki/Conferences">
440                      Conferences
441                      <i class="material-icons">
442                        <img class="go-Icon" height="24" width="24" src="/static/shared/icon/launch_gm_grey_24dp.svg" alt="">
443                      </i>
444                    </a>
445                  </li>
446                  <li class="go-NavigationDrawer-listItem">
447                    <a href="https://go.dev/blog">
448                      Go blog
449                    </a>
450                  </li>
451                  <li class="go-NavigationDrawer-listItem">
452                    <a href="https://go.dev/help">
453                      Go project
454                    </a>
455                  </li>
456                  <li class="go-NavigationDrawer-listItem">
457                    <div>Get connected</div>
458                    <div class="go-Header-socialIcons">
459                        <a class="go-Header-socialIcon" href="https://groups.google.com/g/golang-nuts"><img src="/static/shared/logo/social/google-groups.svg" /></a>
460                        <a class="go-Header-socialIcon" href="https://github.com/golang"><img src="/static/shared/logo/social/github.svg" /></a>
461                        <a class="go-Header-socialIcon" href="https://twitter.com/golang"><img src="/static/shared/logo/social/twitter.svg" /></a>
462                        <a class="go-Header-socialIcon" href="https://www.reddit.com/r/golang/"><img src="/static/shared/logo/social/reddit.svg" /></a>
463                        <a class="go-Header-socialIcon" href="https://invite.slack.golangbridge.org/"><img src="/static/shared/logo/social/slack.svg" /></a>
464                        <a class="go-Header-socialIcon" href="https://stackoverflow.com/collectives/go"><img src="/static/shared/logo/social/stack-overflow.svg" /></a>
465                    </div>
466                  </li>
467                </ul>
468              </div>
469            </div>
470          </li>
471      </ul>
472    </nav>
473  </aside>
474  <div class="go-NavigationDrawer-scrim js-scrim" role="presentation"></div>
475
476    
477  <main class="go-Container" id="main-content">
478    <div class="about-Wrapper">
479      <aside class="LeftNav-sidebar">
480        
481        <nav class="LeftNav" data-hydrate="true"></nav>
482      </aside>
483      <div class="go-Content about-Content">
484        <h1 data-test-id="about-heading">About pkgsite</h1>
485        <p>
486          Welcome to pkg.go.dev, your source for information about Go packages and modules.
487        </p>
488
489        <h2 id="adding-a-package">Adding a package</h2>
490        <p>
491          Data for the site is downloaded from
492          <a href="https://proxy.golang.org/">proxy.golang.org</a>.
493          We monitor the <a href="https://index.golang.org/index">Go Module Index</a>
494          regularly for new packages to add to pkg.go.dev.
495          If you don’t see a package on pkg.go.dev, you can add it by doing one of the following:
496        </p>
497        <ul>
498          <li>
499            <p>
500              Visiting that page on pkg.go.dev, and clicking the “Request” button.
501              For example:
502              <br />
503              <code>https://pkg.go.dev/example.com/my/module</code>
504            </p>
505          </li>
506          <li>
507            <p>
508              Making a request to proxy.golang.org for the module version,
509              to any endpoint specified by the
510              <a href="/cmd/go/#hdr-Module_proxy_protocol">Module proxy protocol</a>.
511              For example:
512              <br />
513              <code>https://proxy.golang.org/example.com/my/module/@v/v1.0.0.info</code>
514            </p>
515          </li>
516          <li>
517            <p>
518              Downloading the package via the
519              <a href="/cmd/go/#hdr-Add_dependencies_to_current_module_and_install_them">go command</a>.
520              For example:
521              <br />
522              <code>GOPROXY=https://proxy.golang.org GO111MODULE=on go get example.com/my/[email protected]</code>
523            </p>
524          </li>
525        </ul>
526
527        <h2 id="removing-a-package">Removing a package</h2>
528        <p>
529          If you would like to hide versions of a module on pkg.go.dev, as well as from the <code>go</code> command,
530          you should retract them. Retracting a module version involves adding a <code>retract</code> directive to
531          your go.mod file and publishing a new version. See the Go blog post
532          <a href="https://go.dev/blog/go116-module-changes#module-retraction">New module changes in Go 1.16</a>
533          and the <a href="https://go.dev/ref/mod#go-mod-file-retract">modules reference</a> for details.
534        </p>
535        <p>
536          Note that it is possible to retract the latest version of a module; the modules reference link above
537          includes an example. Also note that published versions cannot be reused or modified, and this includes
538          retracted versions.
539        </p>
540        <p>
541          If you cannot publish a new version with retractions because the source code repository or domain
542          name is no longer accessible, or if you want to hide documentation for all current and future versions,
543          you can <a href="https://go.dev/s/pkgsite-package-removal">file a request</a> for the pkgsite team to hide
544          your package documentation from pkg.go.dev. Note that the package will continue to be available via
545          <code>go get</code> or <code>go install</code> unless its module is retracted.
546        </p>
547
548        <h2 id="documentation">Documentation</h2>
549        <p>
550          Documentation is generated based on Go source code downloaded from the Go Module Mirror at
551          <code>proxy.golang.org/&lt;module&gt;/@v/&lt;version&gt;.zip</code>.
552          New module versions are fetched from index.golang.org and added to pkg.go.dev site every few minutes.
553        </p>
554        <p>
555          The <a href="https://go.dev/blog/godoc">guidelines for writing documentation</a>
556          for the godoc tool apply to pkg.go.dev.
557        </p>
558        <p>
559          It’s important to write a good summary of the package in the first sentence of the package comment.
560          The go.dev site indexes the first sentence and displays it in search results.
561        </p>
562
563        <h3 id="build-context">Build Context</h3>
564        <p>
565          Most Go packages look and behave the same regardless of the machine architecture
566          or operating system. But some have different documentation, even different
567          exported symbols, for different architectures or OSes. Some packages may not even
568          exist for some architectures.
569        </p>
570        <p>
571          Go calls an OS/architecture pair a “build context” and writes it with a slash,
572          like <code>linux/amd64</code>.
573          You may also see the terms <code>GOOS</code> and <code>GOARCH</code> for the OS
574          and architecture respectively, because those are the names of the environment
575          variables that the go command uses.
576          (See the <a href="/cmd/go">go command documentation</a> for more information.)
577        </p>
578        <p>
579          If a package exists at only one build context, pkg.go.dev displays that build
580          context at the upper right corner of the documentation.
581          For example,
582          <a href="https://pkg.go.dev/syscall/js">https://pkg.go.dev/syscall/js</a>
583          displays “js/wasm”.
584        </p>
585        <p>
586          If a package is different in different build contexts, then pkg.go.dev will
587          display one by default and provide a dropdown control at the upper right so you
588          can select a different one.
589        </p>
590        <p>
591          For packages that are the same across all build contexts, pkg.go.dev does not
592          display any build context information.
593        </p>
594        <p>
595          Although there are many possible OS/architecture pairs, pkg.go.dev considers only a
596          <a href="https://go.googlesource.com/pkgsite/+/master/internal/build_context.go#29">handful</a>
597          of them. So if a package only exists for unsupported build contexts, pkg.go.dev
598          will not display documentation for it.
599        </p>
600
601        <h3 id="source-links">Source Links</h3>
602        <p>
603          Most of the time, pkg.go.dev can determine the location of a package’s source
604          files, and provide links from symbols in the documentation to their definitions
605          in the source. If your package’s source is not linked, try one of the following
606          two approaches.
607        </p>
608        <p>
609          If pkg.go.dev finds a <code>go-source</code> meta tag on your site that follows the
610          <a href="https://github.com/golang/gddo/wiki/Source-Code-Links">specified format</a>,
611          it can often determine the right links, even though the format doesn’t take
612          versioning into account.
613        </p>
614        <p>
615          If that doesn’t work, you will need to add your repo or code-hosting site to
616          pkg.go.dev’s list of patterns
617          (see <a href="https://go.dev/issues/40477">Go Issue 40477</a> for context).
618          Read about how to
619          <a href="https://go.googlesource.com/pkgsite#contributing">contribute to pkg.go.dev</a>,
620          then produce a CL that adds a pattern to the
621          <a href="https://go.googlesource.com/pkgsite/+/refs/heads/master/internal/source/source.go"><code>internal/source</code></a>
622          package.
623        </p>
624
625        <h2 id="best-practices">Best practices</h2>
626        <p>
627          Pkg.go.dev surfaces details about Go packages and modules
628          in order to help provide guidelines for best practices with Go.
629        </p>
630        <p>
631          Here are the details we surface:
632        </p>
633        <ul>
634          <li>
635            <p>
636              <b>Has <code>go.mod</code> file</b>.
637              The Go module system was introduced in Go 1.11
638              and is the official dependency management solution for Go.
639              A module version is defined by a tree of source files,
640              with a go.mod file in its root.
641              <a href="/cmd/go/#hdr-The_go_mod_file">More information about the go.mod file</a>.
642            </p>
643          </li>
644          <li>
645            <p>
646              <b>Redistributable license</b>.
647              Redistributable licenses place minimal restrictions on how software
648              can be used, modified, and redistributed.
649              For more information on how pkg.go.dev determines if a license is redistributable,
650              see our <a href="http://pkg.go.dev/license-policy">license policy</a>.
651            </p>
652          </li>
653          <li>
654            <p>
655              <b>Tagged version</b>.
656              When the go get command resolves modules by default it prioritizes tagged versions.
657              When no tagged versions exist, go get looks up the latest known commit.
658              Modules with tagged versions give importers more predictable builds.
659              See <a href="https://semver.org">semver.org</a> and
660              <a href="https://go.dev/blog/module-compatibility">Keeping Your Modules Compatible</a>
661              for more information.
662            </p>
663          </li>
664          <li>
665            <p>
666              <b>Stable version</b>.
667              Projects at v0 are assumed to be experimental.
668              When a project reaches a stable version – major version v1 or higher –
669              breaking changes must be done in a new major version.
670              Stable versions give developers the confidence that
671              breaking changes won’t occur when they upgrade a package to the latest minor version.
672              See <a href="https://go.dev/blog/v2-go-modules">Go Modules: v2 and Beyond</a>
673              for more information.
674            </p>
675          </li>
676        </ul>
677
678        <h2 id="creating-a-badge">Creating a badge</h2>
679        <p>
680          The pkg.go.dev badge provides a way for Go users to learn about the pkg.go.dev page
681          associated with a given Go package or module.
682          You can create a badge using the <a href="https://pkg.go.dev/badge">badge generation tool</a>.
683          The tool will generate html and markdown snippets
684          that you can use on your project website or in a README file.
685        </p>
686        <p>
687          <a href="https://pkg.go.dev/golang.org/x/pkgsite"><img src="https://pkg.go.dev/badge/golang.org/x/pkgsite" alt="PkgGoDev"></a>
688        </p>
689
690        <h2 id="adding-links">Adding links</h2>
691        <p>
692          You can add links to your README files and package documentation that will be
693          shown on the right side of the pkg.go.dev page.
694          For details, see <a href="https://go.dev/issue/42968">this issue</a>.
695        </p>
696
697        <h2 id="keyboard-shortcuts">Keyboard Shortcuts</h2>
698        <p>
699          There are keyboard shortcuts for navigating package documentation pages.
700          Type ‘?’ on a package page for help.
701        </p>
702
703        <h2 id="bookmarklet">Bookmarklet</h2>
704        <p>
705          The pkg.go.dev bookmarklet navigates from pages on source code hosts,
706          such as GitHub, Bitbucket, Launchpad, etc., to the package documentation.
707          To install the bookmarklet, click and drag the following link to your bookmark bar:
708          <a href="javascript:(function(){ const pathRegex = window.location.pathname.match(/([^\/]+)(?:\/([^\/]+))?/); const host = window.location.hostname; if (pathRegex) { window.location='https://pkg.go.dev/'+host+'/'+pathRegex[0]; } else { alert('There was an error navigating to pkg.go.dev!'); } })()">Pkg.go.dev Doc</a>
709        </p>
710
711        <h2 id="license-policy">License policy</h2>
712        <p>
713          Information for a given package or module may be limited
714          if we are not able to detect a suitable license.
715          See our <a href="https://pkg.go.dev/license-policy">license policy</a> for more information.
716        </p>
717
718        <h2 id="feedback">Feedback</h2>
719        <p>
720          Share your ideas, feature requests, and bugs on the
721          <a href="https://go.dev/s/discovery-feedback">Go Issue Tracker</a>.
722          For questions, please post on the #tools slack channel on the
723          <a href="https://invite.slack.golangbridge.org/">Gophers Slack</a>,
724          or email the <a href="https://groups.google.com/group/golang-dev">golang-dev mailing list</a>.
725        </p>
726
727      </div>
728      <aside class="Sidebar">
729        <h4>Report Issues</h4>
730        <p>If you spot bugs, mistakes, or inconsistencies in the Go project's code or documentation, please let us know by filing a ticket on our <a href="https://github.com/golang/go/issues">issue tracker.</a> Of course, you should check it's not an existing issue before creating a new one.</p>
731        <a class="btn" href="https://github.com/golang/go/issues/new/choose">Filing a ticket</a>
732      </aside>
733    </div>
734  </main>
735
736    
737  <footer class="go-Footer">
738    
739    <div class="go-Footer-links">
740      <div class="go-Footer-linkColumn">
741        <a href="https://go.dev/solutions" class="go-Footer-link go-Footer-link--primary"
742            data-gtmc="footer link">
743          Why Go
744        </a>
745        <a href="https://go.dev/solutions/use-cases" class="go-Footer-link"
746            data-gtmc="footer link">
747          Use Cases
748        </a>
749        <a href="https://go.dev/solutions/case-studies" class="go-Footer-link"
750            data-gtmc="footer link">
751          Case Studies
752        </a>
753      </div>
754      <div class="go-Footer-linkColumn">
755        <a href="https://learn.go.dev/" class="go-Footer-link go-Footer-link--primary"
756            data-gtmc="footer link">
757          Get Started
758        </a>
759        <a href="https://play.golang.org" class="go-Footer-link" data-gtmc="footer link">
760          Playground
761        </a>
762        <a href="https://tour.golang.org" class="go-Footer-link" data-gtmc="footer link">
763          Tour
764        </a>
765        <a href="https://stackoverflow.com/questions/tagged/go?tab=Newest" class="go-Footer-link"
766            data-gtmc="footer link">
767          Stack Overflow
768        </a>
769        <a href="https://go.dev/help" class="go-Footer-link"
770            data-gtmc="footer link">
771          Help
772        </a>
773      </div>
774      <div class="go-Footer-linkColumn">
775        <a href="https://pkg.go.dev" class="go-Footer-link go-Footer-link--primary"
776            data-gtmc="footer link">
777          Packages
778        </a>
779        <a href="/std" class="go-Footer-link" data-gtmc="footer link">
780          Standard Library
781        </a>
782        <a href="/golang.org/x" class="go-Footer-link" data-gtmc="footer link">
783          Sub-repositories
784        </a>
785        <a href="https://pkg.go.dev/about" class="go-Footer-link" data-gtmc="footer link">
786          About Go Packages
787        </a>
788         <a href="/api" class="go-Footer-link" data-gtmc="footer link">
789          pkg.go.dev API
790        </a>
791      </div>
792      <div class="go-Footer-linkColumn">
793        <a href="https://go.dev/project" class="go-Footer-link go-Footer-link--primary"
794            data-gtmc="footer link">
795          About
796        </a>
797        <a href="https://go.dev/dl/" class="go-Footer-link" data-gtmc="footer link">Download</a>
798        <a href="https://go.dev/blog" class="go-Footer-link" data-gtmc="footer link">Blog</a>
799        <a href="https://github.com/golang/go/issues" class="go-Footer-link" data-gtmc="footer link">
800          Issue Tracker
801        </a>
802        <a href="https://go.dev/doc/devel/release.html" class="go-Footer-link"
803            data-gtmc="footer link">
804          Release Notes
805        </a>
806        <a href="https://go.dev/brand" class="go-Footer-link" data-gtmc="footer link">
807          Brand Guidelines
808        </a>
809        <a href="https://go.dev/conduct" class="go-Footer-link" data-gtmc="footer link">
810          Code of Conduct
811        </a>
812      </div>
813      <div class="go-Footer-linkColumn">
814        <a href="https://www.twitter.com/golang" class="go-Footer-link go-Footer-link--primary"
815            data-gtmc="footer link">
816          Connect
817        </a>
818        <a href="https://www.twitter.com/golang" class="go-Footer-link" data-gtmc="footer link">
819          Twitter
820        </a>
821        <a href="https://github.com/golang" class="go-Footer-link" data-gtmc="footer link">GitHub</a>
822        <a href="https://invite.slack.golangbridge.org/" class="go-Footer-link"
823            data-gtmc="footer link">
824          Slack
825        </a>
826        <a href="https://reddit.com/r/golang" class="go-Footer-link" data-gtmc="footer link">
827          r/golang
828        </a>
829        <a href="https://www.meetup.com/pro/go" class="go-Footer-link" data-gtmc="footer link">
830          Meetup
831        </a>
832        <a href="https://golangweekly.com/" class="go-Footer-link" data-gtmc="footer link">
833          Golang Weekly
834        </a>
835      </div>
836    </div>
837    <div class="go-Footer-bottom">
838      <img class="go-Footer-gopher"  width="1431" height="901"
839          src="/static/shared/gopher/pilot-bust-1431x901.svg" alt="Gopher in flight goggles">
840      <ul class="go-Footer-listRow">
841        <li class="go-Footer-listItem">
842          <a href="https://go.dev/copyright" data-gtmc="footer link">Copyright</a>
843        </li>
844        <li class="go-Footer-listItem">
845          <a href="https://go.dev/tos" data-gtmc="footer link">Terms of Service</a>
846        </li>
847        <li class="go-Footer-listItem">
848          <a href="http://www.google.com/intl/en/policies/privacy/" data-gtmc="footer link"
849              target="_blank" rel="noopener">
850            Privacy Policy
851          </a>
852        </li>
853        <li class="go-Footer-listItem">
854          <a href="https://go.dev/s/pkgsite-feedback" target="_blank" rel="noopener"
855              data-gtmc="footer link">
856            Report an Issue
857          </a>
858        </li>
859        <li class="go-Footer-listItem">
860          <button class="go-Button go-Button--text go-Footer-toggleTheme js-toggleTheme" aria-label="Theme Toggle">
861            <img data-value="auto" class="go-Icon go-Icon--inverted" height="24" width="24" src="/static/shared/icon/brightness_6_gm_grey_24dp.svg" alt="System theme">
862            <img data-value="dark" class="go-Icon go-Icon--inverted" height="24" width="24" src="/static/shared/icon/brightness_2_gm_grey_24dp.svg" alt="Dark theme">
863            <img data-value="light" class="go-Icon go-Icon--inverted" height="24" width="24" src="/static/shared/icon/light_mode_gm_grey_24dp.svg" alt="Light theme">
864            <p> Theme Toggle </p>
865          </button>
866        </li>
867        <li class="go-Footer-listItem">
868          <button class="go-Button go-Button--text go-Footer-keyboard js-openShortcuts" aria-label="Shorcuts Modal">
869            <img class="go-Icon go-Icon--inverted" height="24" width="24" src="/static/shared/icon/keyboard_grey_24dp.svg" alt="">
870            <p> Shortcuts Modal </p>
871          </button>
872        </li>
873      </ul>
874      <a class="go-Footer-googleLogo" href="https://google.com" target="_blank"rel="noopener"
875          data-gtmc="footer link">
876        <img class="go-Footer-googleLogoImg" height="24" width="72"
877            src="/static/shared/logo/google-white.svg" alt="Google logo">
878      </a>
879    </div>
880  </footer>
881
882    
883  <dialog id="jump-to-modal" class="JumpDialog go-Modal go-Modal--md js-modal">
884    <form method="dialog" data-gmtc="jump to form" aria-label="Jump to Identifier">
885      <div class="Dialog-title go-Modal-header">
886        <h2>Jump to</h2>
887        <button
888          class="go-Button go-Button--inline"
889          type="button"
890          data-modal-close
891          data-gtmc="modal button"
892          aria-label="Close"
893        >
894          <img
895            class="go-Icon"
896            height="24"
897            width="24"
898            src="/static/shared/icon/close_gm_grey_24dp.svg"
899            alt=""
900          />
901        </button>
902      </div>
903      <div class="JumpDialog-filter">
904        <input class="JumpDialog-input go-Input" autocomplete="off" type="text">
905      </div>
906      <div class="JumpDialog-body go-Modal-body">
907        <div class="JumpDialog-list"></div>
908      </div>
909      <div class="go-Modal-actions">
910        <button class="go-Button" data-test-id="close-dialog">Close</button>
911      </div>
912    </form>
913  </dialog>
914
915  <dialog class="ShortcutsDialog go-Modal go-Modal--sm js-modal">
916    <form method="dialog">
917      <div class="go-Modal-header">
918        <h2>Keyboard shortcuts</h2>
919        <button
920          class="go-Button go-Button--inline"
921          type="button"
922          data-modal-close
923          data-gtmc="modal button"
924          aria-label="Close"
925        >
926          <img
927            class="go-Icon"
928            height="24"
929            width="24"
930            src="/static/shared/icon/close_gm_grey_24dp.svg"
931            alt=""
932          />
933        </button>
934      </div>
935      <div class="go-Modal-body">
936        <table>
937          <tbody>
938            <tr><td class="ShortcutsDialog-key">
939              <strong>?</strong></td><td> : This menu</td>
940            </tr>
941            <tr><td class="ShortcutsDialog-key">
942              <strong>/</strong></td><td> : Search site</td>
943            </tr>
944            <tr><td class="ShortcutsDialog-key">
945              <strong>f</strong> or <strong>F</strong></td><td> : Jump to</td>
946            </tr>
947            <tr>
948              <td class="ShortcutsDialog-key"><strong>y</strong> or <strong>Y</strong></td>
949              <td> : Canonical URL</td>
950            </tr>
951          </tbody>
952        </table>
953      </div>
954      <div class="go-Modal-actions">
955        <button class="go-Button" data-test-id="close-dialog">Close</button>
956      </div>
957    </form>
958  </dialog>
959
960    
961      <section class="Cookie-notice js-cookieNotice">
962        <div>
962go.dev uses cookies from Google to deliver and enhance the quality of its services and to
963        analyze traffic. <a target=_blank href="https://policies.google.com/technologies/cookies">Learn more.</a></div>
964        <div><button class="go-Button">Okay</button></div>
965      </section>
966    
967    
968      
968<script>
969        // this will throw if the querySelector can’t find the element
970        const gtmId = document.querySelector('.js-gtmID').dataset.gtmid;
971        if (!gtmId) {
972          throw new Error('Google Tag Manager ID not found');
973        }
974        loadScript(`https://www.googletagmanager.com/gtm.js?id=${gtmId}`);
975      </script>
vendor: 83 bytes, lines 975-977
975
976      <noscript>
977        <iframe src="https://www.googletagmanager.com/ns.html?id=
977GTM-W8MVQXG
vendor: 127 bytes, lines 977-983
977"
978                height="0" width="0" style="display:none;visibility:hidden">
979        </iframe>
980      </noscript>
981    
982    
983  
983</body>
984</html>

Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.