From 8a00e3941651ee0ba509b2f57aa835b2544c66f1 Mon Sep 17 00:00:00 2001 From: Radovan Bast Date: Wed, 19 Mar 2025 11:11:05 +0100 Subject: [PATCH 1/2] shorten the concepts episode; closes #297 --- content/concepts.md | 122 +++++++++++++++++--------------------------- 1 file changed, 46 insertions(+), 76 deletions(-) diff --git a/content/concepts.md b/content/concepts.md index 0e52362..f8c60f7 100644 --- a/content/concepts.md +++ b/content/concepts.md @@ -1,22 +1,8 @@ # Concepts around collaboration -```{objectives} +:::{objectives} - Be able to decide whether to divide work at the branch level or at the repository level. -``` - -```{instructor-note} -- 15 min teaching -``` - - -## Motivation - -- Someone has given you access to a repository online and you want to contribute? -- We will learn how to make a copy and send changes back. -- Then, we make a "pull request" that allows a review. -- Once we know how code review works, we will be able to propose changes - to repositories of others and review changes submitted by external - contributors. +::: ## Commits, branches, repositories, forks, clones @@ -33,68 +19,41 @@ ## Cloning a repository -In order to make a complete copy a whole repository, the `git clone` command can be used. When cloning, all the files, of all or selected branches, of a repository are copied in one operation. Cloning of a repository is of relevance in a few different situations: -* Working on your own, cloning is the operation that you can use to create multiple instances of a repository on, for instance, a personal computer, a server, and a supercomputer. -* The parent repository could be a repository that you or your colleague own. A common use case for cloning is when working together within a smaller team where everyone has read and write access to the same git repository. -* Alternatively, cloning can be made from a public repository of a code that you would like to use. Perhaps you have no intention to work on the code, but would like to stay in tune with the latest developments, also in-between releases of new versions of the code. - -```{figure} img/overview/clone.png -:alt: Cloning +In order to make a complete copy a whole repository, the `git clone` command +can be used. When cloning, all the files, of all or selected branches, of a +repository are copied in one operation. Cloning of a repository is of relevance +in a few different situations: +* Working on your own, cloning is the operation that you can use to create + multiple instances of a repository on, for instance, a personal computer, a + server, and a supercomputer. +* The parent repository could be a repository that you or your colleague own. A + common use case for cloning is when working together within a smaller team + where everyone has read and write access to the same git repository. +* Alternatively, cloning can be made from a public repository of a code that + you would like to use. Perhaps you have no intention to work on the code, but + would like to stay in tune with the latest developments, also in-between + releases of new versions of the code. + + +:::{figure} img/overview/forkandclone.png +:alt: Forking and cloning :width: 100% :class: with-border -Cloning -``` +Forking and cloning +::: ## Forking a repository -When a fork is made on GitHub/GitLab a complete copy, of all or selected branches, of the repository is made. The copy will reside under a different account on GitHub/GitLab. Forking of a repository is of high relevance when working with a git repository to which you do not have write access. -* In the fork repository commits can be made to the base branch (`main` or `master`), and to other branches. -* The commits that are made within the branches of the fork repository can be contributed back to the parent repository by means of pull or merge requests. - -```{figure} img/overview/fork.png -:alt: Forking -:width: 100% -:class: with-border - -Forking -``` - - -## Generating from templates and importing - -There are two more ways to create "copies" of repositories into your user space: -- A repository can be marked as **template** and new repositories can be - **generated** from it, like using a cookie-cutter. - The newly created repository will start with a new history, only one commit, and not - inherit the history of the template. - -```{figure} img/overview/generate.png -:alt: Generating from a template -:width: 100% -:class: with-border - -Generating from a template. -``` - -- You can **import** a repository from another hosting service or web address. - This will preserve the history of the imported project. - -```{figure} img/overview/import.png -:alt: Importing a repository -:width: 100% -:class: with-border - -Importing a repository. -``` ---- - -```{discussion} -- Visit one of the repositories/projects that you have used recently and try to find out - how many forks exist and where they are. -- In which situations could it be useful to start from a "template" repository by generating? -``` +When a fork is made on GitHub/GitLab a complete copy, of all or selected +branches, of the repository is made. The copy will reside under a different +account on GitHub/GitLab. Forking of a repository is of high relevance when +working with a git repository to which you do not have write access. +- In the fork repository commits can be made to the base branch (`main` or + `master`), and to other branches. +- The commits that are made within the branches of the fork repository can be + contributed back to the parent repository by means of pull or merge requests. ## Synchronizing changes between repositories @@ -105,12 +64,23 @@ Importing a repository. - We will learn how to suggest changes within repositories on GitHub and across repositories (**pull request**). - Repositories that are forked or cloned do not automatically synchronize themselves: We will learn how to update forks (by pulling from the "central" repository). -- A main difference between cloning a repository and forking a repository is that the former is a general operation for generating copies of a repository to different computers, whereas forking is a particular operation implemented on GitHub/GitLab. +- A main difference between cloning a repository and forking a repository is that the former + is a general operation for generating copies of a repository to different computers, + whereas forking is a particular operation implemented on GitHub/GitLab. -```{figure} img/overview/forkandclone.png -:alt: Forking and cloning + +## Generating from templates + +A repository can be marked as **template** and new repositories can be +**generated** from it, like using a cookie-cutter. + +The newly created repository will start with a new ("flattened") history, only one commit, and not +inherit the history of the template. + +:::{figure} img/overview/generate.png +:alt: Generating from a template :width: 100% :class: with-border -Forking and cloning -``` +Generating from a template. +::: From 9e9a1401cb1484cacf04364c8d312281df3c53ca Mon Sep 17 00:00:00 2001 From: Radovan Bast Date: Wed, 19 Mar 2025 11:16:17 +0100 Subject: [PATCH 2/2] clarify better when to clone and when to fork; closes #289 --- content/concepts.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/content/concepts.md b/content/concepts.md index f8c60f7..3b26f68 100644 --- a/content/concepts.md +++ b/content/concepts.md @@ -69,6 +69,18 @@ working with a git repository to which you do not have write access. whereas forking is a particular operation implemented on GitHub/GitLab. +## Should we clone or fork? + +Should we all work on forks or should we all work inside one repository? + +- For most small or medium-sized research projects you probably want to **work by + cloning a repository** that all research group has write access to (we will + exercise this in the next section). + +- It's only when you want to contribute to a project that you don't have write + access to that you need to use **forks** (we will practice this as well). + + ## Generating from templates A repository can be marked as **template** and new repositories can be