Git Workflow - Revision history

Jwrm2: /* Checking out an older version of the master branch */ Formatted checkout command as code.

2025-07-30T10:15:49Z

Checking out an older version of the master branch: Formatted checkout command as code.

← Older revision		Revision as of 10:15, 30 July 2025
Line 145:		Line 145:
	See the documentation for git diff for example. To check out the master branch current at a given date you can use:		See the documentation for git diff for example. To check out the master branch current at a given date you can use:

	git checkout `git rev-list -1 --before="Feb 11 2024" master`		$ git checkout `git rev-list -1 --before="Feb 11 2024" master`

	==Writing a Paper==		==Writing a Paper==

Jwrm2: /* Creating a new submodule */ More details about adding a new submodule.

2025-07-30T10:15:15Z

Creating a new submodule: More details about adding a new submodule.

← Older revision		Revision as of 10:15, 30 July 2025
Line 93:		Line 93:

	where my_new_repository is replaced with whatever you named the new repository. You could also got the appropriate URL by going onto Gitlab for the new repository, clicking the 'Clone' button and copying. This command makes the necessary changes to the .gitmodules file, which will then need to be committed and pushed.		where my_new_repository is replaced with whatever you named the new repository. You could also got the appropriate URL by going onto Gitlab for the new repository, clicking the 'Clone' button and copying. This command makes the necessary changes to the .gitmodules file, which will then need to be committed and pushed.

			If the external potential already exists in some other repository and you will not need to make any changes to it at all, you can add the external repository directly rather than copying and using up space on our Gitlab. LAMMPS was added in this way, with a command like

			$ git submodule add https://github.com/lammps/lammps.git

			This approach is only likely to work for public repositories that do not need any kind of password to clone.

			There are a couple of useful options to be aware of. Commands like the above will create a new directory with the name of the repository. You can use a custom name by adding it after the repository URL. The command will use the default branch of the repository (usually 'master' or 'main'), but you can specify a different branch with the -b flag. For example

			$ git submodule add -b metatomic https://github.com/metatensor/lammps.git lammps_petmad

			will clone the metatomic branch of the lammps repository from metatensor, but put it in the directory lammps_petmad.

	Turning an existing subdirectory into a submodule is also possible, but is slightly more complicated and is considered an advanced topic. Google is your friend. Do not mess with the Gitlab repository until you are satisfied you have made the correct adjustments locally.		Turning an existing subdirectory into a submodule is also possible, but is slightly more complicated and is considered an advanced topic. Google is your friend. Do not mess with the Gitlab repository until you are satisfied you have made the correct adjustments locally.

Dw34 at 20:24, 22 July 2024

2024-07-22T20:24:21Z

← Older revision		Revision as of 20:24, 22 July 2024
Line 127:		Line 127:

	Note that the remote can function as the backup of your work. Therefore you should probably push any new commits at least as often as the end of each day.		Note that the remote can function as the backup of your work. Therefore you should probably push any new commits at least as often as the end of each day.

			==Checking out an older version of the master branch==

			There are all sorts of useful git tools for checking how individual files and branches have changed.
			See the documentation for git diff for example. To check out the master branch current at a given date you can use:

			git checkout `git rev-list -1 --before="Feb 11 2024" master`

	==Writing a Paper==		==Writing a Paper==

Jwrm2: /* Writing a Paper */ Fixed bib repository link.

2023-08-08T09:33:06Z

Writing a Paper: Fixed bib repository link.

← Older revision		Revision as of 09:33, 8 August 2023
Line 143:		Line 143:
	Do not add intermediate LaTeX files (.aux, .log, etc.) to the repository. Do not add your .dvi/.ps/.pdf documents either (except perhaps for proofs created by the journal). When it comes to revisions and resubmissions, do not create a new subdirectory for the new version. Git keeps the whole history so it is always possible to revert to a previous version.		Do not add intermediate LaTeX files (.aux, .log, etc.) to the repository. Do not add your .dvi/.ps/.pdf documents either (except perhaps for proofs created by the journal). When it comes to revisions and resubmissions, do not create a new subdirectory for the new version. Git keeps the whole history so it is always possible to revert to a previous version.

	You will also want to checkout the [~~git@~~gitlab.developers.cam.ac.uk:ch/wales/bib~~.git~~ bibliography repository] but you only need one copy of this, not one for each paper. A suitable directory structure might be to have a papers/ directory under your home directory that contains a directory for the bibliography repository and a directory for each paper you are currently working on.		You will also want to checkout the [https://gitlab.developers.cam.ac.uk/ch/wales/bib bibliography repository] but you only need one copy of this, not one for each paper. A suitable directory structure might be to have a papers/ directory under your home directory that contains a directory for the bibliography repository and a directory for each paper you are currently working on.

	==Working on the group code==		==Working on the group code==

Jwrm2: /* Writing a Paper */ Updated to reflect having a repository per paper.

2023-08-08T09:31:55Z

Writing a Paper: Updated to reflect having a repository per paper.

← Older revision		Revision as of 09:31, 8 August 2023
Line 130:		Line 130:
	==Writing a Paper==		==Writing a Paper==

	Writing a paper is slightly simpler than editing the group code (Discuss...) because we aren't worrying about multiple branches. ~~Create~~ a new ~~directory~~ ~~for~~ your ~~paper~~ and ~~use~~ ~~git~~ ~~add~~ to ~~add~~ it. ~~Start~~ writing the paper in the ~~new~~ directory. Each session of editing should involve		Writing a paper is slightly simpler than editing the group code (Discuss...) because we aren't worrying about multiple branches. Each paper is a separate repository. To start a new paper, go to Gitlab and create a new repository by clicking the blue 'New Project' button on your home screen. Create a blank project and make sure the project URL indicates it is under ch/wales rather than in your user space. Checkout the new repository and start writing the paper in the blank directory. Each session of editing should involve

	# git pull		# git pull
Line 141:		Line 141:
	Simples. All authors will be editing the same branch (the master branch), so you'll see other authors' updates straight away. This approach keeps things easy, but if two authors are working at exactly the same time, there may be some merging to do. Reduce the amount of merging by committing, pulling and pushing often.		Simples. All authors will be editing the same branch (the master branch), so you'll see other authors' updates straight away. This approach keeps things easy, but if two authors are working at exactly the same time, there may be some merging to do. Reduce the amount of merging by committing, pulling and pushing often.

	Do not add intermediate LaTeX files (.aux, .log, etc.) to the repository. Do not add your .dvi/.ps/.pdf ~~document~~ either. ~~These~~ ~~extensions~~ ~~are~~ ~~all~~ ~~specified~~ in the .~~gitignore~~ ~~file~~ ~~for~~ ~~the~~ ~~papers~~ ~~repository,~~ so ~~they~~ ~~will~~ not ~~show~~ up ~~with~~ ~~git~~ ~~status.~~ ~~If you are~~ ~~using~~ .~~pdf~~ or ~~.ps~~ ~~for~~ ~~your~~ ~~images,~~ ~~you~~ ~~should~~ ~~still~~ be ~~able~~ to ~~add~~ ~~them~~ ~~with~~ ~~git~~ ~~add~~. ~~You will need to add them individually however, with~~		Do not add intermediate LaTeX files (.aux, .log, etc.) to the repository. Do not add your .dvi/.ps/.pdf documents either (except perhaps for proofs created by the journal). When it comes to revisions and resubmissions, do not create a new subdirectory for the new version. Git keeps the whole history so it is always possible to revert to a previous version.

	$ git add -f filename
			You will also want to checkout the [git@gitlab.developers.cam.ac.uk:ch/wales/bib.git bibliography repository] but you only need one copy of this, not one for each paper. A suitable directory structure might be to have a papers/ directory under your home directory that contains a directory for the bibliography repository and a directory for each paper you are currently working on.
	and cannot add all files at the same time (i.e. using git add -A).

	==Working on the group code==		==Working on the group code==

Jwrm2: /* Initial Checkout */ Updated Gitlab link.

2023-08-08T09:22:06Z

Initial Checkout: Updated Gitlab link.

← Older revision		Revision as of 09:22, 8 August 2023
Line 51:		Line 51:
	==Initial Checkout==		==Initial Checkout==

	You need to fetch the repository. In Git terms, this is called cloning. You should only need to carry out this step once for each repository. In your favourite web browser, navigate to the project page on Gitlab, eg. [https://gitlab.developers.cam.ac.uk/ch/wales/softwarewales ~~papers~~]. Spot the blue button on the right labelled 'Clone' and click on it. Copy the link under 'Clone with SSH' to the clipboard (don't use the 'clone with HTTPS' link, or you will have to type your username and password every time). In a terminal, choose a suitable location, like your home directory and change to there. Now type		You need to fetch the repository. In Git terms, this is called cloning. You should only need to carry out this step once for each repository. In your favourite web browser, navigate to the project page on Gitlab, eg. [https://gitlab.developers.cam.ac.uk/ch/wales/softwarewales software]. Spot the blue button on the right labelled 'Clone' and click on it. Copy the link under 'Clone with SSH' to the clipboard (don't use the 'clone with HTTPS' link, or you will have to type your username and password every time). In a terminal, choose a suitable location, like your home directory and change to there. Now type

	$ git clone git@gitlab.developers.cam.ac.uk:ch/wales/softwarewales.git		$ git clone git@gitlab.developers.cam.ac.uk:ch/wales/softwarewales.git

Jwrm2: /* Initial Checkout */ Changed from papers to software.

2023-08-08T09:21:18Z

Initial Checkout: Changed from papers to software.

← Older revision		Revision as of 09:21, 8 August 2023
Line 51:		Line 51:
	==Initial Checkout==		==Initial Checkout==

	You need to fetch the repository. In Git terms, this is called cloning. You should only need to carry out this step once for each repository. In your favourite web browser, navigate to the project page on Gitlab, eg. [https://gitlab.developers.cam.ac.uk/ch/wales/~~paperswales~~ papers]. Spot the blue button on the right labelled 'Clone' and click on it. Copy the link under 'Clone with SSH' to the clipboard (don't use the 'clone with HTTPS' link, or you will have to type your username and password every time). In a terminal, choose a suitable location, like your home directory and change to there. Now type		You need to fetch the repository. In Git terms, this is called cloning. You should only need to carry out this step once for each repository. In your favourite web browser, navigate to the project page on Gitlab, eg. [https://gitlab.developers.cam.ac.uk/ch/wales/softwarewales papers]. Spot the blue button on the right labelled 'Clone' and click on it. Copy the link under 'Clone with SSH' to the clipboard (don't use the 'clone with HTTPS' link, or you will have to type your username and password every time). In a terminal, choose a suitable location, like your home directory and change to there. Now type

	$ git clone git@gitlab.developers.cam.ac.uk:ch/wales/~~paperswales~~.git		$ git clone git@gitlab.developers.cam.ac.uk:ch/wales/softwarewales.git

	replacing the address with what you just copied. Git will download the repository. Once it has finished, check that you now have lots of new directories with the contents of the repository.		replacing the address with what you just copied. Git will download the repository. Once it has finished, check that you now have lots of new directories with the contents of the repository.

Jwrm2: /* Working on the group code */ Instructed to compile with nagfor before merging.

2023-08-08T09:19:47Z

Working on the group code: Instructed to compile with nagfor before merging.

← Older revision		Revision as of 09:19, 8 August 2023
Line 167:		Line 167:
	The pull commands makes sure that your local copy of the repository is up to date. The merge command merges changes that have been made to the master branch to your branch. It creates new commits, that you then push to the remote of your branch.		The pull commands makes sure that your local copy of the repository is up to date. The merge command merges changes that have been made to the master branch to your branch. It creates new commits, that you then push to the remote of your branch.

	Most users do not have permission to edit the master branch. To get your new feature in, you have to create a merge request. Go to the project page on GitLab. From the drop down menu of branches, select exciting_feature. Click the blue 'Create merge request' button in the top right. You now have a page in which you can give your merge request a title and description. You ~~can~~ ~~also~~ ~~choose~~ ~~who~~ to ~~assign~~ it to. Make sure you tick the boxes to delete the feature branch after the request is accepted~~, and to squash your branch into one commit~~. These options help keep the remote repository and history clean. You can edit the commit message for the one commit that will be created: by default it will be the name of your branch. The person you ~~assign~~ to will get a notification and a copy of your changes. They will look through your changes to make sure they follow the group coding standards ([https://wikis.ch.cam.ac.uk/wales/wiki/index.php/Wales_Group_Fortran_conventions_for_group_software here]) and that you haven't broken anything. If there are any issues, they may request that you make some changes, which you can then commit to the exciting_feature branch. The pull request will be updated and the reviewer will get a notification. Once your code has passed the review, the reviewer will click the Merge button and your branch will be merged into master. Just 'Approve' from the reviewer won't usually be enough because you probably don't have permission to write to Master and hence cannot merge your new branch into master yourself. Once it has been merged, you can clean up your repository with the following commands		Most users do not have permission to edit the master branch. To get your new feature in, you have to create a merge request. Go to the project page on GitLab. From the drop down menu of branches, select exciting_feature. Click the blue 'Create merge request' button in the top right. You now have a page in which you can give your merge request a title and description. You should assign the request to yourself and anyone else who has worked on this branch. Choose the person who is going to review for you. Make sure you tick the boxes to delete the feature branch after the request is accepted. These options help keep the remote repository and history clean. You can edit the commit message for the one commit that will be created: by default it will be the name of your branch. The person you select as reviewer will get a notification and a copy of your changes. They will look through your changes to make sure they follow the group coding standards ([https://wikis.ch.cam.ac.uk/wales/wiki/index.php/Wales_Group_Fortran_conventions_for_group_software here]) and that you haven't broken anything. If there are any issues, they may request that you make some changes, which you can then commit to the exciting_feature branch. The pull request will be updated and the reviewer will get a notification. However, the reviewer will not be doing extensive testing, so it remains your responsibility to follow the coding standards and make sure everything works. You should make sure your changes compile with nagfor before submitting the merge request, as that is the most particular compiler. Once your code has passed the review, the reviewer will click the Merge button and your branch will be merged into master. Just 'Approve' from the reviewer won't usually be enough because you probably don't have permission to write to Master and hence cannot merge your new branch into master yourself. Once it has been merged, you can clean up your repository with the following commands

	$ git checkout master		$ git checkout master

Jwrm2: /* Submodules */ Typos

2023-01-26T16:30:32Z

Submodules: Typos

← Older revision		Revision as of 16:30, 26 January 2023
Line 66:		Line 66:
	==Submodules==		==Submodules==

	Our software repository has become quite large as external potentials have been added. Submodules offer a way to compartmentalise the ~~reporistory~~ and speed up clones and updates. Self-contained third-party potentials are good candidates for splitting off into submodules. We will use GDML (Gradient-Descent Machine Learning) as an example. On an initial checkout, you will see a GDML/ directory in the root of the repository, but the ~~directpory~~ will be empty. Most users do not need GDML, so will not care or even be particularly aware that GDML has not be cloned.		Our software repository has become quite large as external potentials have been added. Submodules offer a way to compartmentalise the repository and speed up clones and updates. Self-contained third-party potentials are good candidates for splitting off into submodules. We will use GDML (Gradient-Descent Machine Learning) as an example. On an initial checkout, you will see a GDML/ directory in the root of the repository, but the directory will be empty. Most users do not need GDML, so will not care or even be particularly aware that GDML has not be cloned.

	Let us suppose that you actually need GDML. You can tell git that it is required by running		Let us suppose that you actually need GDML. You can tell git that it is required by running
Line 76:		Line 76:
	$ git submodule update		$ git submodule update

	the contents of GDML will be checked out. If GDML is subsequently updated, run the update command again to get the newest version. If at some later point you decide that you have ~~finihsed~~ with GDML and no longer need it checked out, run		the contents of GDML will be checked out. If GDML is subsequently updated, run the update command again to get the newest version. If at some later point you decide that you have finished with GDML and no longer need it checked out, run

	$ git submodule deinit GDML		$ git submodule deinit GDML
Line 94:		Line 94:
	where my_new_repository is replaced with whatever you named the new repository. You could also got the appropriate URL by going onto Gitlab for the new repository, clicking the 'Clone' button and copying. This command makes the necessary changes to the .gitmodules file, which will then need to be committed and pushed.		where my_new_repository is replaced with whatever you named the new repository. You could also got the appropriate URL by going onto Gitlab for the new repository, clicking the 'Clone' button and copying. This command makes the necessary changes to the .gitmodules file, which will then need to be committed and pushed.

	~~Turing~~ an existing subdirectory into a submodule is also possible, but is slightly more complicated and is considered an advanced topic. Google is your friend. Do not mess with the Gitlab repository until you are satisfied you have made the correct adjustments locally.		Turning an existing subdirectory into a submodule is also possible, but is slightly more complicated and is considered an advanced topic. Google is your friend. Do not mess with the Gitlab repository until you are satisfied you have made the correct adjustments locally.

	==Basic Workflow==		==Basic Workflow==

Jwrm2: /* Creating a new submodule */ Typos

2022-12-19T13:43:28Z

Creating a new submodule: Typos

← Older revision		Revision as of 13:43, 19 December 2022
Line 94:		Line 94:
	where my_new_repository is replaced with whatever you named the new repository. You could also got the appropriate URL by going onto Gitlab for the new repository, clicking the 'Clone' button and copying. This command makes the necessary changes to the .gitmodules file, which will then need to be committed and pushed.		where my_new_repository is replaced with whatever you named the new repository. You could also got the appropriate URL by going onto Gitlab for the new repository, clicking the 'Clone' button and copying. This command makes the necessary changes to the .gitmodules file, which will then need to be committed and pushed.

	Turing an existing subdirectory into a submodule is also possible, but is slightly more complicated and is considered ~~and~~ advanced topic. Google is your friend. Do not mess with the Gitlab repository until you are satisfied you have made the correct adjustments locally.		Turing an existing subdirectory into a submodule is also possible, but is slightly more complicated and is considered an advanced topic. Google is your friend. Do not mess with the Gitlab repository until you are satisfied you have made the correct adjustments locally.

	==Basic Workflow==		==Basic Workflow==