Create or Clone a Project¶

Follow route 1a + 2 OR route 1b + 2.

0) First-time Git Users¶

If you have not used Git before, you probably haven’t configured it yet. At least run the following (with correct name and email):

git config --global init.defaultBranch main
git config --global user.name "Your Name"
git config --global user.email "Your.Name@email.com"
git config --global core.editor nano

Also, go through a Git Tutorial to become familiar with the basic concepts.

1a) Start a New Publication¶

Start a new publication using the cookiecutter:
```
cookiecutter https://github.com/reproducible-reporting/templates
```
Follow the instructions on the terminal. You will need to enter:
- slug: This is a short name for the directory containing all sources and compiled outputs. Use only lower-case characters, digits and hyphens.
- article: The LaTeX article template you want to use.
- supp: The LaTeX supporting of supplementary information template you want to use.
- cover: The LaTeX template for the cover letter.
Enter the newly created directory (slug) and initialize the Git repository
```
cd 'slug'
git init
```
Replace 'slug' with the directory created by the cookiecutter.
Before making a first commit, define the software requirements, e.g., for post-processing and plotting, in requirements.in and/or environment.yaml. Pin versions of your dependencies with ==X.Y.Z as shown in the example files in the template.
- If you must use micromamba, because you have non-Python dependencies, you can remove requirements.in and setup-venv-pip.sh.
- If you prefer to create a pure Python project, you can remove environment.yaml and setup-venv-micromamba.sh.
Note that the Python environment uses pip-tools to manage dependencies. This facilitates reproducibility because the results of the package dependency calculation are stored in requirements.txt and this file is also committed to the Git repository
Now you can add all the files, commit them, define a remote URL and push the initial contents online:
```
git add .
git commit -a -m "Initial commit"
git remote add origin 'remote url'
git push origin main -u
```
Replace 'remote url' with the correct one. This depends on which online service is used to share the Git repository with your co-authors. If in doubt, create a private repository on GitHub.

1b) Clone an Existing Publication¶

You need a 'remote url' of an existing publication, which one of your co-authors created. Substitute this 'remote url' in the following command, which should be executed in the terminal:

git clone 'remote url'
cd 'slug'

Replace 'slug' with the directory created by git clone.

2) Set Up the Software Environment¶

(It is assumed that your current working directory is the 'slug' defined in the previous section 1a or 1b.)

Install the software environment, using ONE of the following commands (NOT more than one):
- Fedora or Ubuntu 24:
```
./setup-venv-pip.sh
```
- Ubuntu 22
```
PYTHON3=python3.11 ./setup-venv-pip.sh
```
- Any OS but requires more resources
```
./setup-venv-micromamba.sh
```
Activate your software environment:
```
source .envrc
```
This activation is required each time you open a new terminal. It is not recommended to add publication-specific activation scripts to your ~/.bashrc. If you find it too tedious to run the activation script over and over again, try using direnv. Once direnv is installed and configured in your shell profile, you only need to allow it once with direnv allow ., and the .envrc script is automatically sourced when you change to the directory of the Git repository.
Install pre-commit and git-lfs into the new repository:
```
pre-commit install
git-lfs install
```
This is needed each time you create or clone a Git repository. Normally, that is only once per publication.
You should now be able to build the template manuscript and related documents with StepUp RepRep as follows:
```
cd latest-draft
stepup -n
```