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