GitLabgitlab-org
cli
main
1package list
3import (
4 "fmt"
5 "net/url"
6 "strings"
8 "github.com/MakeNowJust/heredoc/v2"
9 "github.com/spf13/cobra"
11 gitlab "gitlab.com/gitlab-org/api/client-go/v3"
13 "gitlab.com/gitlab-org/cli/internal/api"
14 "gitlab.com/gitlab-org/cli/internal/cmdutils"
15 "gitlab.com/gitlab-org/cli/internal/iostreams"
16 "gitlab.com/gitlab-org/cli/internal/mcpannotations"
17 "gitlab.com/gitlab-org/cli/internal/tableprinter"
18 "gitlab.com/gitlab-org/cli/internal/utils"
19)
21type options struct {
22 apiClient func(repoHost string) (*api.Client, error)
23 io *iostreams.IOStreams
25 // Pagination
26 page int
27 perPage int
29 title string
30 search string
31 state string
32 includeAncestors bool
33 includeDescendants bool
35 groupID string
36 projectID string
37 showIDs bool
38 outputFormat string
39}
41func NewCmdList(f cmdutils.Factory) *cobra.Command {
42 opts := &options{
43 io: f.IO(),
44 apiClient: f.ApiClient,
45 }
46 cmd := &cobra.Command{
47 Use: "list [flags]",
48 Short: "List milestones in a project or group.",
49 Long: heredoc.Docf(`
50 Filter by state with %[1]s--state%[1]s (%[1]sactive%[1]s or %[1]sclosed%[1]s), by title with %[1]s--title%[1]s,
51 or by free-text search with %[1]s--search%[1]s. For group milestones, use
52 %[1]s--include-ancestors%[1]s to also include milestones from ancestor groups, and
53 %[1]s--include-descendants%[1]s to also include milestones from subgroups and descendant projects.
55 By default, milestones are listed for the current project. Use
56 %[1]s--project%[1]s to target a different project, or %[1]s--group%[1]s to list
57 group-level milestones. %[1]s--project%[1]s and %[1]s--group%[1]s are mutually exclusive.
59 Use %[1]s--output json%[1]s to format the result as JSON for use with other tools.
60 `, "`"),
61 Example: heredoc.Doc(`
62 # List milestones in a project
63 glab milestone list --project 123
64 glab milestone list --project owner/project
66 # List milestones in a group
67 glab milestone list --group example-group
69 # List only active milestones in a group
70 glab milestone list --group example-group --state active
72 # List group milestones, including those from ancestor groups
73 glab milestone list --group example-group --include-ancestors
75 # List group milestones, including those from subgroups and descendant projects
76 glab milestone list --group example-group --include-descendants
78 # List milestones as JSON
79 glab milestone list --project owner/project --output json
80 `),
81 Args: cobra.NoArgs,
82 ValidArgsFunction: cobra.NoFileCompletions,
83 Annotations: map[string]string{
84 mcpannotations.Safe: "true",
85 },
86 RunE: func(cmd *cobra.Command, args []string) error {
87 return opts.run(cmd)
88 },
89 }
91 cmd.Flags().StringVar(&opts.projectID, "project", "", "The ID or URL-encoded path of the project.")
92 cmd.Flags().StringVar(&opts.groupID, "group", "", "The ID or URL-encoded path of the group.")
94 cmd.Flags().StringVar(&opts.title, "title", "", "Return only the milestones having the given title.")
95 cmd.Flags().StringVar(&opts.search, "search", "", "Return only milestones with a title or description matching the provided string.")
96 cmd.Flags().StringVar(&opts.state, "state", "", "Return only 'active' or 'closed' milestones.")
97 cmd.Flags().BoolVar(&opts.includeAncestors, "include-ancestors", false, "Include milestones from all parent groups.")
98 cmd.Flags().BoolVar(&opts.includeDescendants, "include-descendants", false, "Include milestones from all subgroups and descendant projects.")
100 cmd.Flags().IntVarP(&opts.page, "page", "p", 1, "Page number.")
101 cmd.Flags().IntVarP(&opts.perPage, "per-page", "P", 20, "Number of items to list per page.")
102 cmd.Flags().BoolVar(&opts.showIDs, "show-id", false, "Show IDs in table output.")
103 cmdutils.EnableJSONOutput(cmd, opts.io, &opts.outputFormat)
105 cmd.MarkFlagsOneRequired("project", "group")
106 cmd.MarkFlagsMutuallyExclusive("project", "include-descendants")
108 return cmd
109}
111func (o *options) run(cmd *cobra.Command) error {
112 c, err := o.apiClient("")
113 if err != nil {
114 return err
115 }
116 client := c.Lab()
118 if o.projectID != "" { // list project milestones
119 listMilestonesOptions := &gitlab.ListMilestonesOptions{
120 ListOptions: gitlab.ListOptions{
121 PerPage: int64(o.perPage),
122 Page: int64(o.page),
123 },
124 }
126 if o.title != "" {
127 listMilestonesOptions.Title = &o.title
128 }
129 if o.search != "" {
130 listMilestonesOptions.Search = &o.search
131 }
132 if o.state != "" {
133 listMilestonesOptions.State = &o.state
134 }
135 if cmd.Flags().Changed("include-ancestors") {
136 listMilestonesOptions.IncludeAncestors = &o.includeAncestors
137 }
139 milestones, _, err := client.Milestones.ListMilestones(o.projectID, listMilestonesOptions)
140 if err != nil {
141 return err
142 }
144 if o.outputFormat == "json" {
145 return o.io.PrintJSON(milestones)
146 }
148 if len(milestones) == 0 {
149 o.io.LogInfo("No milestones found.")
150 return nil
151 }
153 table := tableprinter.NewTablePrinter()
154 if o.showIDs {
155 table.AddRow("ID", "Title", "Description", "State", "Due Date")
156 for _, m := range milestones {
157 table.AddRow(m.ID, m.Title, m.Description, m.State, utils.FormatDueDate(m.DueDate))
158 }
159 } else {
160 table.AddRow("Title", "Description", "State", "Due Date")
161 for _, m := range milestones {
162 table.AddRow(m.Title, m.Description, m.State, utils.FormatDueDate(m.DueDate))
163 }
164 }
166 o.io.LogInfo(table.String())
167 return nil
168 } else if o.groupID != "" { // list group milestones
169 listMilestonesOptions := &gitlab.ListGroupMilestonesOptions{
170 ListOptions: gitlab.ListOptions{
171 Page: int64(o.page),
172 PerPage: int64(o.perPage),
173 },
174 }
176 if o.title != "" {
177 listMilestonesOptions.Title = &o.title
178 }
179 if o.search != "" {
180 listMilestonesOptions.Search = &o.search
181 }
182 if o.state != "" {
183 listMilestonesOptions.State = &o.state
184 }
185 if cmd.Flags().Changed("include-ancestors") {
186 listMilestonesOptions.IncludeAncestors = &o.includeAncestors
187 }
188 if cmd.Flags().Changed("include-descendants") {
189 listMilestonesOptions.IncludeDescendents = &o.includeDescendants
190 }
192 milestones, _, err := client.GroupMilestones.ListGroupMilestones(o.groupID, listMilestonesOptions)
193 if err != nil {
194 return err
195 }
197 if o.outputFormat == "json" {
198 return o.io.PrintJSON(milestones)
199 }
201 if len(milestones) == 0 {
202 o.io.LogInfo("No milestones found.")
203 return nil
204 }
206 table := tableprinter.NewTablePrinter()
207 var header []any
208 if o.showIDs {
209 header = append(header, "ID")
210 }
211 header = append(header, "Title")
212 if o.includeDescendants {
213 header = append(header, "Owner")
214 }
215 header = append(header, "Description", "State", "Due Date")
216 table.AddRow(header...)
218 basePath := instanceBasePath(client)
220 for _, m := range milestones {
221 var row []any
222 if o.showIDs {
223 row = append(row, m.ID)
224 }
225 row = append(row, m.Title)
226 if o.includeDescendants {
227 row = append(row, milestoneOwner(m, basePath))
228 }
229 row = append(row, m.Description, m.State, utils.FormatDueDate(m.DueDate))
230 table.AddRow(row...)
231 }
233 o.io.LogInfo(table.String())
234 return nil
235 }
237 return nil
238}
240func instanceBasePath(client *gitlab.Client) string {
241 p := strings.TrimSuffix(client.BaseURL().Path, "/")
242 return strings.TrimSuffix(p, "/api/v4")
243}
245func milestoneOwner(m *gitlab.GroupMilestone, basePath string) string {
246 if m == nil {
247 return ""
248 }
249 if m.WebURL != "" {
250 if u, err := url.Parse(m.WebURL); err == nil && u.Path != "" {
251 p := u.Path
252 if basePath != "" {
253 basePath = "/" + strings.Trim(basePath, "/")
254 if after, ok := strings.CutPrefix(p, basePath+"/"); ok {
255 p = "/" + after
256 } else if p == basePath {
257 p = ""
258 }
259 }
260 if idx := strings.Index(p, "/-/milestones/"); idx != -1 {
261 p = p[:idx]
262 } else if idx := strings.Index(p, "/milestones/"); idx != -1 {
263 p = p[:idx]
264 } else {
265 p = ""
266 }
267 if after, ok := strings.CutPrefix(p, "/groups/"); ok {
268 p = after
269 } else if p == "/groups" {
270 p = ""
271 }
272 p = strings.Trim(p, "/")
273 if p != "" {
274 return p
275 }
276 }
277 }
278 if m.ProjectID != 0 {
279 return fmt.Sprintf("project/%d", m.ProjectID)
280 }
281 if m.GroupID != 0 {
282 return fmt.Sprintf("group/%d", m.GroupID)
283 }
284 return ""
285}
Diagnostics8 git calls · 215 ms
CallStatusSizeTime0215 ms
discover200185 B2 ms
git.upload-pack discover http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=2 git.response.bytes=185 git.server.agent=git/2.56.g1891de4-Linux git.server.object_format=sha1 git.server.caps=agent ls-refs fetch server-option object-format git.server.fetch=shallow wait-for-done filter git.protocol.version=2 git.pkt.frames=9 git.pkt.data=7 git.pkt.flush=2 git.pkt.delim=0 git.pkt.bytes=185 git.pkt.payload.max=35
ls-refs20058 KiB3 ms
git.upload-pack ls-refs http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=2 git.response.bytes=59849 git.response.cache=UPDATING git.response.duration_ms=3 git.protocol.version=2 git.pkt.frames=731 git.pkt.data=730 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=59849 git.pkt.payload.max=143 git.ls_refs.count=730 git.ls_refs.head=refs/heads/main
fetchtree:0 · deepen 1020032 KiB · hit2 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=2 git.response.bytes=32926 git.response.cache=HIT git.response.duration_ms=2 git.fetch.filter=tree:0 git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9 git.fetch.haves.count=0 git.fetch.deepen=10 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=22 git.pkt.data=20 git.pkt.flush=1 git.pkt.delim=1 git.pkt.bytes=32926 git.pkt.payload.max=32046 git.sideband.band1.bytes=32046 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=80 git.pack.bytes=32046 git.pack.ofs_delta=36 git.pack.ref_delta=0 git.pack.chain.max=2 git.pack.trailer=cb0bad5d7ffc514895d8b21c4dd470327f90bc91 git.pack.full=44Open pack map
fetchcombine:blob:none+tree:2 · deepen 12004.2 KiB · hit2 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=2 git.response.bytes=4273 git.response.cache=HIT git.response.duration_ms=2 git.fetch.filter=combine:blob:none+tree:2 git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9 git.fetch.haves.count=0 git.fetch.deepen=1 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=7 git.pkt.data=5 git.pkt.flush=1 git.pkt.delim=1 git.pkt.bytes=4273 git.pkt.payload.max=4173 git.sideband.band1.bytes=4173 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=11 git.pack.bytes=4173 git.fetch.wide.objects=11 git.fetch.wide.extra_bytes=3930 git.fetch.wide.blobs=0
fetchtree:02001.8 KiB · hit4 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=4 git.response.bytes=1857 git.response.cache=HIT git.response.duration_ms=4 git.fetch.filter=tree:0 git.fetch.wants=dce174ff8c632a19d17eea99c8a9b7c37fb2b592 git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=1857 git.pkt.payload.max=1830 git.sideband.band1.bytes=1830 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=1 git.pack.bytes=1830 git.pack.trailer=fb03183b7909876778f740d196d7516811003517Open pack map
fetchtree:0200287 B · hit2 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=2 git.response.bytes=287 git.response.cache=HIT git.response.duration_ms=2 git.fetch.filter=tree:0 git.fetch.wants=4b2a62b649e97f7e66e5dd178207a12ec137d596 git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=287 git.pkt.payload.max=260 git.sideband.band1.bytes=260 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=1 git.pack.bytes=260 git.pack.trailer=6593eafdcd01a12bbd3c8da0f75aaca8bc99568fOpen pack map
fetchtree:0200133 B · hit3 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=3 git.response.bytes=133 git.response.cache=HIT git.response.duration_ms=3 git.fetch.filter=tree:0 git.fetch.wants=04833289db4cc01186c55b0c646287b76a4b090e git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=133 git.pkt.payload.max=106 git.sideband.band1.bytes=106 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=1 git.pack.bytes=106 git.pack.trailer=d6fdc89fd5de86abfc32dcc9e6cda7ee8fe1971eOpen pack map
fetch2002.3 KiB201 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=201 git.response.bytes=2403 git.response.cache=MISS git.response.duration_ms=201 git.fetch.wants=4de4f9144683c03e8e8306d2a8773dbd087c036c git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=2403 git.pkt.payload.max=2376 git.sideband.band1.bytes=2376 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0
Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.
- Remote
- https://gitlab.com/gitlab-org/cli
- Ref
- refs/heads/main
- Commit
- 0dd7574dce9e385c5c30540e6c15657adc6bdce9
- cf-ray
- a5e2de2a1d662308
- Request
- 77024d37…
- Protocol
- v2 · sha1
- Agent
- git/2.56.g1891de4-Linux
- Filter
- advertised
- Fetch
- shallow wait-for-done filter
- Capabilities
- agent ls-refs fetch server-option object-format