Option to `Select default_branch` is not honored

[kmatch98]

I just ran the cookie cutter and tried to select main as the default_branch (option 2):

When the cookiecutter repo was created, it only has a master branch:

[hugodahl]

I've looked into this some, and it appears that this isn't directly an issue with CookieCutter or the template.

By default, the CookieCutter template, as it currently exists, does not initialize a git repository in the target directory. As such, it is up to the person who ran the cookiecutter ... command to perform the git init step. This is where the branch name mismatch happens since git will take the currently defined init.defaultBranch value. If no value is set, then the git default of master is used.

Because of these factors, there two ways in which this issue can be addressed:

1. Remove the default branch name option/value from the cookie-cutter template, letting whatever the user's system has configured (or defaulted)
2. As part of the cookiecutter post-commit hook (in /hooks/post_gen_project.py), initialize the git repository for the user.

There are a few options and caveats to consider with option 2:

• We cannot rename a branch before a commit has been made. That means we would need to create an initial commit in the repository, which we can do.
  • Should we create an absolutely empty repository, without any files? This would seem possibly problematic and might appear pointless.
  • We could add all the files currently in the directory, as this would be the "clean" output from the cookiecutter. However, even the clean output from the cookiecutter leaves some issues which snag pre-commit, such as the presence of TODO strings in the code files. It would be up to the user to either handle those if they install pre-commit, or when they push to GitHub and get CI workflow failures
  • We could add just a subset of the files which are pre-determined. That could still potentially have the same issues as in the previous point.

I personally prefer the 2nd option, running the git init for the user to create the repository and set whatever needs to be set.

As far as which file(s) to include in the initial commit, if any, I have no inclination toward any of the options, and would defer that decision to others.

For what it helps, should we choose to go with option 2 (run git init for the user), I think that these would be the commands for each scenario:

Empty repo

git init
git commit --allow-empty -m "Initial commit"
git branch -M {{cookiecutter.default_branch}}

Include all generated files

git init
git add .
git commit -m "Initial commit"
git branch -M {{cookiecutter.default_branch}}

Subset of files:

git init
git add file1 file2 file3 ... file_n  # or perhaps from a value defined within the /cookiecutter.json file
git commit -m "Initial commit"
git branch -M {{cookiecutter.default_branch}}

[askpatrickw]

My only thought is if we're going to then have to deal with git not being setup correctly...
I also think it would be good for beginners if we directed them towards using the GitHub CLI instead of the lower level git.
https://cli.github.com/ GitHub is putting a lot of energy into making a higher-level (easier to use) cli more suitable for the core CP audience.

[hugodahl]

That's a good point @askpatrickw, and I appreciate you bringing it up. That does take into account the assumption that the user is using GitHub, where they might (never say never) use BitBucket, GitLab or another hosted Git provider.

However, at the point where this would run in the CookieCutter process, the user hasn't gotten to perform any operations in the repo - from the CLI or otherwise. This portion all happens as part of the directory staging happening before any development happens.

[jepler]

It's worth noting that you can use a URL like https://github.com/adafruit/cookiecutter-adafruit-circuitpython/blob/HEAD/README.rst (note HEAD instead of main or master) to point to a file on the default branch, without naming that branch.

That doesn't help with making it work across different git hosting services, though

[askpatrickw]

I wasn't thinking about supporting other Git hosting platforms at all. This is all setup to work work with GitHub Actions. It could have a "Git Host" question, but I don't think the current community needs that.

I was just saying, that if we do git init or something, then we're asking the user to have git setup correctly already (or even installed).

@jepler, that is an excellent suggestion. The only place we're using default_branch is in URL paths to the Code of Conduct... using HEAD is probably a better solution, and we could remove the question from the cookiecutter workflow.

OR we could also try to init a repo for them.

I think both answers are perfectly reasonable.
One is less work and removes code. so I'd lean that way but only a little.

[hugodahl]

I was just saying, that if we do git init or something, then we're asking the user to have git setup correctly already (or even installed).

That's a good point, about them having git installed. Although one would think that if they're at the stage where someone is creating a library, whether it's for personal use or to share with the community, they would have some of the tooling installed.

Perhaps that's something that would need to be explicitly called out in the "Creating and Sharing a CircuitPython Library" learn guide, which is likely where the instructions to use cookie-cutter came from.

@jepler, that is an excellent suggestion. The only place we're using default_branch is in URL paths to the Code of Conduct... using HEAD is probably a better solution, and we could remove the question from the cookiecutter workflow.

I agree, when using remotes, particularly "unknown" ones, using HEAD as the principal branch reference, rather than an explicit name, helps remove that complexity.

So, coming back full circle to this issue then, I think there are 2 1/2 possible options:

1. Remove the question, and let the library author manage the initialization of the git repository, along with the default branch name. This ensures that the author has full, 100% control of the outcome.
2. Initialize the repository, and specify the default branch name. This makes a few assumptions, namely that the author has the git CLI installed, and that the global configuration (i.e. git config --global) is done.
3. (Option 2 1/2): Same as option 2 above, but explicitly specify an author (name + email) such as "CircuitPython CookieCutter no-reply@somedomain.tld" (email TBD) so that user configuration is a non-issue, but still requires git be installed. This may create other issues, however, with regards to authorship, licensing, copyright, etc.

[askpatrickw]

I Vote 1️⃣ :-)