doc: describe the url-parse builtin
The new url-parse builtin validates git URLs and optionally extracts their components. Helped-by: Ghanshyam Thakkar <shyamthakkar001@gmail.com> Signed-off-by: Matheus Afonso Martins Moreira <matheus@matheusmoreira.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Matheus Afonso Martins Moreira committed
May 2, 2026 at 05:28 UTC
d1671b13dc3c5d87368bd09604540ad0a8ed33b5
2 files changed
+81
Documentation/git-url-parse.adoc
new
+80
@@ -0,0 +1,80 @@
1
+git-url-parse(1)
2
+================
3
+
4
+NAME
5
+----
6
+git-url-parse - Parse and extract git URL components
7
+
8
+SYNOPSIS
9
+--------
10
+[synopsis]
11
+git url-parse [-c <component>] [--] <url>...
12
+
13
+DESCRIPTION
14
+-----------
15
+
16
+Git supports many ways to specify URLs, some of them non-standard.
17
+For example, git supports the scp style [user@]host:[path] format.
18
+This command eases interoperability with git URLs by enabling the
19
+parsing and extraction of the components of all git URLs.
20
+
21
+Any syntactically valid URL is parsed, even if the scheme is not one
22
+git supports for fetching or pushing.
23
+
24
+OPTIONS
25
+-------
26
+
27
+`-c <component>`::
28
+`--component <component>`::
29
+ Extract the _<component>_ component from the given Git URLs.
30
+ _<component>_ can be one of:
31
+ `scheme`, `user`, `password`, `host`, `port`, `path`.
32
+
33
+OUTPUT
34
+------
35
+
36
+When `--component` is given, the requested component of each URL
37
+is printed on its own line, in the order the URLs were given. If
38
+the URL has no such component (for example, a port in a URL that
39
+does not specify one), an empty line is printed in its place.
40
+
41
+When `--component` is not given, no output is produced. The exit
42
+status is zero if every URL parses successfully and non-zero
43
+otherwise, allowing the command to be used purely as a validator.
44
+
45
+EXAMPLES
46
+--------
47
+
48
+* Print the host name:
49
++
50
+------------
51
+$ git url-parse --component host https://example.com/user/repo
52
+example.com
53
+------------
54
+
55
+* Print the path:
56
++
57
+------------
58
+$ git url-parse --component path https://example.com/user/repo
59
+/user/repo
60
+$ git url-parse --component path example.com:~user/repo
61
+~user/repo
62
+$ git url-parse --component path example.com:user/repo
63
+/user/repo
64
+------------
65
+
66
+* Validate URLs without outputting anything:
67
++
68
+------------
69
+$ git url-parse https://example.com/user/repo example.com:~user/repo
70
+------------
71
+
72
+SEE ALSO
73
+--------
74
+linkgit:git-clone[1],
75
+linkgit:git-fetch[1],
76
+linkgit:git-config[1]
77
+
78
+GIT
79
+---
80
+Part of the linkgit:git[1] suite
Documentation/meson.build
+1
@@ -155,6 +155,7 @@ manpages = {
155
'git-update-server-info.adoc' : 1,
156
'git-upload-archive.adoc' : 1,
157
'git-upload-pack.adoc' : 1,
158
+ 'git-url-parse.adoc' : 1,
159
'git-var.adoc' : 1,
160
'git-verify-commit.adoc' : 1,
161
'git-verify-pack.adoc' : 1,