1 | # hosted-git-info
|
2 |
|
3 | This will let you identify and transform various git hosts URLs between
|
4 | protocols. It also can tell you what the URL is for the raw path for
|
5 | particular file for direct access without git.
|
6 |
|
7 | ## Example
|
8 |
|
9 | ```javascript
|
10 | const hostedGitInfo = require("hosted-git-info")
|
11 | const info = hostedGitInfo.fromUrl("git@github.com:npm/hosted-git-info.git", opts)
|
12 | /* info looks like:
|
13 | {
|
14 | type: "github",
|
15 | domain: "github.com",
|
16 | user: "npm",
|
17 | project: "hosted-git-info"
|
18 | }
|
19 | */
|
20 | ```
|
21 |
|
22 | If the URL can't be matched with a git host, `null` will be returned. We
|
23 | can match git, ssh and https urls. Additionally, we can match ssh connect
|
24 | strings (`git@github.com:npm/hosted-git-info`) and shortcuts (eg,
|
25 | `github:npm/hosted-git-info`). GitHub specifically, is detected in the case
|
26 | of a third, unprefixed, form: `npm/hosted-git-info`.
|
27 |
|
28 | If it does match, the returned object has properties of:
|
29 |
|
30 | * info.type -- The short name of the service
|
31 | * info.domain -- The domain for git protocol use
|
32 | * info.user -- The name of the user/org on the git host
|
33 | * info.project -- The name of the project on the git host
|
34 |
|
35 | ## Version Contract
|
36 |
|
37 | The major version will be bumped any time…
|
38 |
|
39 | * The constructor stops accepting URLs that it previously accepted.
|
40 | * A method is removed.
|
41 | * A method can no longer accept the number and type of arguments it previously accepted.
|
42 | * A method can return a different type than it currently returns.
|
43 |
|
44 | Implications:
|
45 |
|
46 | * I do not consider the specific format of the urls returned from, say
|
47 | `.https()` to be a part of the contract. The contract is that it will
|
48 | return a string that can be used to fetch the repo via HTTPS. But what
|
49 | that string looks like, specifically, can change.
|
50 | * Dropping support for a hosted git provider would constitute a breaking
|
51 | change.
|
52 |
|
53 | ## Usage
|
54 |
|
55 | ### const info = hostedGitInfo.fromUrl(gitSpecifier[, options])
|
56 |
|
57 | * *gitSpecifer* is a URL of a git repository or a SCP-style specifier of one.
|
58 | * *options* is an optional object. It can have the following properties:
|
59 | * *noCommittish* — If true then committishes won't be included in generated URLs.
|
60 | * *noGitPlus* — If true then `git+` won't be prefixed on URLs.
|
61 |
|
62 | ## Methods
|
63 |
|
64 | All of the methods take the same options as the `fromUrl` factory. Options
|
65 | provided to a method override those provided to the constructor.
|
66 |
|
67 | * info.file(path, opts)
|
68 |
|
69 | Given the path of a file relative to the repository, returns a URL for
|
70 | directly fetching it from the githost. If no committish was set then
|
71 | `HEAD` will be used as the default.
|
72 |
|
73 | For example `hostedGitInfo.fromUrl("git@github.com:npm/hosted-git-info.git#v1.0.0").file("package.json")`
|
74 | would return `https://raw.githubusercontent.com/npm/hosted-git-info/v1.0.0/package.json`
|
75 |
|
76 | * info.shortcut(opts)
|
77 |
|
78 | eg, `github:npm/hosted-git-info`
|
79 |
|
80 | * info.browse(path, fragment, opts)
|
81 |
|
82 | eg, `https://github.com/npm/hosted-git-info/tree/v1.2.0`,
|
83 | `https://github.com/npm/hosted-git-info/tree/v1.2.0/package.json`,
|
84 | `https://github.com/npm/hosted-git-info/tree/v1.2.0/REAMDE.md#supported-hosts`
|
85 |
|
86 | * info.bugs(opts)
|
87 |
|
88 | eg, `https://github.com/npm/hosted-git-info/issues`
|
89 |
|
90 | * info.docs(opts)
|
91 |
|
92 | eg, `https://github.com/npm/hosted-git-info/tree/v1.2.0#readme`
|
93 |
|
94 | * info.https(opts)
|
95 |
|
96 | eg, `git+https://github.com/npm/hosted-git-info.git`
|
97 |
|
98 | * info.sshurl(opts)
|
99 |
|
100 | eg, `git+ssh://git@github.com/npm/hosted-git-info.git`
|
101 |
|
102 | * info.ssh(opts)
|
103 |
|
104 | eg, `git@github.com:npm/hosted-git-info.git`
|
105 |
|
106 | * info.path(opts)
|
107 |
|
108 | eg, `npm/hosted-git-info`
|
109 |
|
110 | * info.tarball(opts)
|
111 |
|
112 | eg, `https://github.com/npm/hosted-git-info/archive/v1.2.0.tar.gz`
|
113 |
|
114 | * info.getDefaultRepresentation()
|
115 |
|
116 | Returns the default output type. The default output type is based on the
|
117 | string you passed in to be parsed
|
118 |
|
119 | * info.toString(opts)
|
120 |
|
121 | Uses the getDefaultRepresentation to call one of the other methods to get a URL for
|
122 | this resource. As such `hostedGitInfo.fromUrl(url).toString()` will give
|
123 | you a normalized version of the URL that still uses the same protocol.
|
124 |
|
125 | Shortcuts will still be returned as shortcuts, but the special case github
|
126 | form of `org/project` will be normalized to `github:org/project`.
|
127 |
|
128 | SSH connect strings will be normalized into `git+ssh` URLs.
|
129 |
|
130 | ## Supported hosts
|
131 |
|
132 | Currently this supports GitHub (including Gists), Bitbucket, GitLab and Sourcehut.
|
133 | Pull requests for additional hosts welcome.
|