gitea_sdk/api/repos/mod.rs
1pub mod branches;
2pub mod commits;
3pub mod delete;
4pub mod edit;
5pub mod forks;
6pub mod get;
7
8/// The [Repos] struct provides methods for interacting with repositories.
9pub struct Repos {
10 pub(crate) owner: String,
11 pub(crate) repo: String,
12}
13
14impl Repos {
15 /// Deletes a repository by its owner and name.
16 /// WARNING: This is irreversible and will delete all data associated with the repository.
17 /// This action cannot be undone. When invoking this method, you will not be asked for
18 /// confirmation. Use with caution, please don't nuke your repositories.
19 ///
20 /// # Example
21 /// ```rust
22 /// # use gitea_sdk::{Client, Auth};
23 /// # async fn delete_repo() {
24 /// let client = Client::new(
25 /// "https://gitea.example.com",
26 /// Auth::Token("your-token")
27 /// );
28 /// client
29 /// .repos("owner", "repo")
30 /// .delete()
31 /// .send(&client)
32 /// .await
33 /// .unwrap();
34 /// # }
35 /// ```
36 pub fn delete(&self) -> delete::DeleteRepoBuilder {
37 delete::DeleteRepoBuilder::new(&self.owner, &self.repo)
38 }
39 /// Gets a repository by its owner and name.
40 /// This will return a [Repository] object if the repository exists and is visible to the
41 /// currently authenticated user.
42 ///
43 /// # Example
44 /// ```rust
45 /// # use gitea_sdk::{Client, Auth};
46 /// # async fn get_repo() {
47 /// let client = Client::new(
48 /// "https://gitea.example.com",
49 /// Auth::Token("your-token")
50 /// );
51 /// let repo = client
52 /// .repos("owner", "repo")
53 /// .get()
54 /// .send(&client)
55 /// .await
56 /// .unwrap();
57 /// # }
58 /// ```
59 ///
60 pub fn get(&self) -> get::GetRepoBuilder {
61 get::GetRepoBuilder::new(&self.owner, &self.repo)
62 }
63
64 /// Forks a repository by its owner and name.
65 /// The [CreateForkOption] struct provides a number of optional fields to customize the fork,
66 /// but all fields are entirely optional.
67 /// If you don't set any fields, the fork will be created with the same name as the original
68 /// repository in the authenticated user's account.
69 ///
70 /// # Examples
71 ///
72 /// ```rust
73 /// # use gitea_sdk::{Client, Auth};
74 /// # async fn fork_repo() {
75 /// let client = Client::new(
76 /// "https://gitea.example.com",
77 /// Auth::Token("your-token")
78 /// );
79 /// let forked_repo = client
80 /// .repos("owner", "repo")
81 /// .create_fork()
82 /// .name("my-fork")
83 /// .send(&client)
84 /// .await
85 /// .unwrap();
86 /// # }
87 /// ```
88 /// This will fork the repository "owner/repo" into the authenticated user's account with the
89 /// name "my-fork".
90 ///
91 /// ```rust
92 /// # use gitea_sdk::{Client, Auth};
93 /// # async fn fork_repo() {
94 /// let client = Client::new(
95 /// "https://gitea.example.com",
96 /// Auth::Token("your-token")
97 /// );
98 /// let forked_repo = client
99 /// .repos("owner", "repo")
100 /// .create_fork()
101 /// .organization("my-org")
102 /// .send(&client)
103 /// .await
104 /// .unwrap();
105 /// # }
106 /// ```
107 /// This will fork the repository "owner/repo" into the organization "my-org" with the same
108 /// name as the original repository.
109 ///
110 /// ```rust
111 /// # use gitea_sdk::{Client, Auth};
112 /// # async fn fork_repo() {
113 /// let client = Client::new(
114 /// "https://gitea.example.com",
115 /// Auth::Token("your-token")
116 /// );
117 /// let created_repo = client
118 /// .user()
119 /// .create_repo("my-new-repo")
120 /// .send(&client)
121 /// .await
122 /// .unwrap();
123 /// let forked_repo = client
124 /// .repos("owner", "my-new-repo")
125 /// .create_fork()
126 /// .name("my-new-repo")
127 /// .send(&client)
128 /// .await
129 /// .expect_err("Repository with the same name should already exist for the current user");
130 /// # }
131 /// ```
132 /// This will create a new repository with the name "my-new-repo" for the authenticated user,
133 /// then attempt to fork the repository "owner/repo" into the authenticated user's account.
134 /// The fork will fail because a repository with the same name already exists.
135 pub fn create_fork(&self) -> forks::CreateForkBuilder {
136 forks::CreateForkBuilder::new(&self.owner, &self.repo)
137 }
138
139 /// Edits a repository by its owner and name.
140 ///
141 /// If you don't set any fields, the repository will not be modified.
142 ///
143 /// # Example
144 /// ```rust
145 /// # use gitea_sdk::{Client, Auth};
146 /// # async fn edit_repo() {
147 /// let client = Client::new(
148 /// "https://gitea.example.com",
149 /// Auth::Token("your-token")
150 /// );
151 /// let repo = client
152 /// .repos("owner", "repo")
153 /// .edit()
154 /// .description("A new description")
155 /// .send(&client)
156 /// .await
157 /// .unwrap();
158 /// # }
159 /// ```
160 /// This will set the description of the repository "owner/repo" to "A new description".
161 /// If you want to remove the description, you can set it to an empty string.
162 pub fn edit(&self) -> edit::EditRepoBuilder {
163 edit::EditRepoBuilder::new(&self.owner, &self.repo)
164 }
165
166 /// Lists the forks of a repository by its owner and name.
167 pub fn get_forks(&self) -> forks::ListForksBuilder {
168 forks::ListForksBuilder::new(&self.owner, &self.repo)
169 }
170
171 /// Gets a list of commits for a repository.
172 /// The [GetCommitsOption] struct provides a number of optional fields to filter the results,
173 /// but all fields are entirely optional.
174 /// If you don't set any fields, you will get the most recent commits for the default branch.
175 ///
176 /// # Example
177 /// ```
178 /// # use gitea_sdk::{Client, api::repos::commits::GetCommitsBuilder, Auth};
179 /// # async fn get_commits() {
180 /// let client = Client::new(
181 /// "https://gitea.example.com",
182 /// Auth::Token("your-token")
183 /// );
184 /// let commits = client
185 /// .repos("owner", "repo")
186 /// .get_commits()
187 /// .send(&client)
188 /// .await
189 /// .unwrap();
190 /// # }
191 /// ```
192 pub fn get_commits(&self) -> commits::GetCommitsBuilder {
193 commits::GetCommitsBuilder::new(&self.owner, &self.repo)
194 }
195
196 /// Lists a repository's branches.
197 ///
198 /// # Example
199 /// ```
200 /// # use gitea_sdk::{Client, Auth};
201 /// # async fn list_branches() {
202 /// let client = Client::new(
203 /// "https://gitea.example.com",
204 /// Auth::Token("your-token")
205 /// );
206 /// let branches = client
207 /// .repos("owner", "repo")
208 /// .list_branches()
209 /// .send(&client)
210 /// .await
211 /// .unwrap();
212 /// # }
213 /// ```
214 /// This will list the branches for the repository "owner/repo".
215 pub fn list_branches(&self) -> branches::ListBranchesBuilder {
216 branches::ListBranchesBuilder::new(&self.owner, &self.repo)
217 }
218
219 /// Creates a new branch in a repository.
220 ///
221 /// # Example
222 /// ```
223 /// # use gitea_sdk::{Client, Auth};
224 /// # async fn create_branch() {
225 /// let client = Client::new(
226 /// "https://gitea.example.com",
227 /// Auth::Token("your-token")
228 /// );
229 /// client
230 /// .repos("owner", "repo")
231 /// .create_branch("new-branch")
232 /// .old_ref_name("main")
233 /// .send(&client)
234 /// .await
235 /// .unwrap();
236 /// # }
237 /// ```
238 /// This will create a new branch named "new-branch" in the repository "owner/repo" based on
239 /// the "main" branch.
240 ///
241 /// ```
242 /// # use gitea_sdk::{Client, Auth};
243 /// # async fn create_branch() {
244 /// let client = Client::new(
245 /// "https://gitea.example.com",
246 /// Auth::Token("your-token")
247 /// );
248 /// client
249 /// .repos("owner", "repo")
250 /// .create_branch("new-branch")
251 /// .send(&client)
252 /// .await
253 /// .unwrap();
254 /// # }
255 /// ```
256 /// This will create a new empty branch named "new-branch" in the repository "owner/repo"
257 pub fn create_branch(&self, new_branch_name: impl ToString) -> branches::CreateBranchBuilder {
258 branches::CreateBranchBuilder::new(&self.owner, &self.repo, new_branch_name)
259 }
260
261 /// Gets a branch in a repository.
262 /// This will return a [Branch](crate::model::repos::Branch) object if the branch exists.
263 ///
264 /// # Example
265 /// ```
266 /// # use gitea_sdk::{Client, Auth};
267 /// # async fn get_branch() {
268 /// let client = Client::new(
269 /// "https://gitea.example.com",
270 /// Auth::Token("your-token")
271 /// );
272 /// let branch = client
273 /// .repos("owner", "repo")
274 /// .get_branch("main")
275 /// .send(&client)
276 /// .await
277 /// .unwrap();
278 /// # }
279 /// ```
280 /// This will get the branch "main" in the repository "owner/repo".
281 pub fn get_branch(&self, branch: impl ToString) -> branches::GetBranchBuilder {
282 branches::GetBranchBuilder::new(&self.owner, &self.repo, branch)
283 }
284
285 /// Deletes a branch in a repository.
286 /// WARNING: This is irreversible and will delete all data associated with the branch.
287 /// This action cannot be undone. When invoking this method, you will not be asked for
288 /// confirmation. Use with caution
289 ///
290 /// # Example
291 /// ```
292 /// # use gitea_sdk::{Client, Auth};
293 /// # async fn delete_branch() {
294 /// let client = Client::new(
295 /// "https://gitea.example.com",
296 /// Auth::Token("your-token")
297 /// );
298 /// client
299 /// .repos("owner", "repo")
300 /// .delete_branch("branch-to-delete")
301 /// .send(&client)
302 /// .await
303 /// .unwrap();
304 /// # }
305 /// ```
306 /// This will delete the branch "branch-to-delete" in the repository "owner/repo".
307 pub fn delete_branch(&self, branch: impl ToString) -> branches::DeleteBranchBuilder {
308 branches::DeleteBranchBuilder::new(&self.owner, &self.repo, branch)
309 }
310}