Adding an IsGitRepository type parameter

[qtzar]

Currently there are two main options for building a site, one if use the workspace.dsl file in the local specified directory and the other is to specify a GitHub repository and loop the specified branches to use the workspace file in those branches.

I build my site via GitHub Actions which already does the cloning of the site and then uses the local workspace.dsl file option to generate the site, but that means that I can't generate the sites for multiple branches.

I'm wondering how useful it might be to have some sort of command line parameter like -isGitRepository which would generate the site similar to the option of adding a repository url but skipping the cloning part because it is already cloned.

I'd also love to see the -branches parameter expanded to all an option for 'all branches' while introducing a -ExcludeBranch option to remove certain branches (Like a gh-page branch that will hole the generated site). This would allow different architects or engineers to create a branch to build out a future state model, push it to the repository and have it build automatically without them having to add the branch name to the GitHub actions.

If you think there is interest in this idea I'd love to take an attempt at adding it.

[jp7677]

Thanks for starting the discussion.

I'm wondering how useful it might be to have some sort of command line parameter like -isGitRepository which would generate the site similar to the option of adding a repository url but skipping the cloning part because it is already cloned.

I think we should just auto detect if the workspace file is part of a git working space. If that is the case, we should honor the branches and default-branch switch. On the other hand, I'm not really sure if it is a good idea to modify an existing source directly and leave it in a different state (by checking out other branches) once generation is completed? Also what to do with dirty working spaces?

I'd also love to see the -branches parameter expanded to all an option for 'all branches' while introducing a -ExcludeBranch option to remove certain branches (Like a gh-page branch that will hole the generated site).

Yes, I like that idea and I've also recently thought that having this would be cool. Regarding the command line UI, I would just extend the branches switch, e.g. supporting * as a wildcard and ![branch name] for exclusion.

There are a few things to consider:

• How to handle faulting branches? I guess it is wise to not break site generation for all branches when a single branch has e.g. an invalid dsl file. That said, I guess it is wise to bail out when master /main is broken for fail-fast.
• Detecting what exactly "all branch" are might be more tricky than it seems, e.g. what to do with tags?
• Should we fetch all remote branches or just look at local branches when the dsl location is already a git working space (like your example from your GitHub action)?

Lets see what @dirkgroot thinks..

[dirkgroot]

I also think that adding an option for including all branches in the generated site is a good idea.

On the other hand, I'm not really sure if it is a good idea to modify an existing source directly and leave it in a different state (by checking out other branches) once generation is completed? Also what to do with dirty working spaces?

This is why I decided to always start from a freshly cloned repository when generating a site from a Git repository. It prevents us from having to deal with these kinds of edge cases. I think that it is wise to always assume that people are going to use this not only from build pipelines, but also from their local development machine.

Regarding the command line UI, I would just extend the branches switch, e.g. supporting * as a wildcard and ![branch name] for exclusion.

I'm not so sure about the * wildcard, because I'm afraid this will interfere with globbing functionality of the shell you're executing the command in. I think I prefer @qtzar's idea of having separate --all-branches and --exclude-branches options.

How to handle faulting branches? I guess it is wise to not break site generation for all branches when a single branch has e.g. an invalid dsl file. That said, I guess it is wise to bail out when master /main is broken for fail-fast.

I think we should always bail out if one branch fails. That way it's easy to spot errors in either your CI pipeline configuration or in the C4 model on a failing branch. I think that adding a "conditional bailout" like you describe would just make things more complex, with no real benefit to make up for that added complexity.

Detecting what exactly "all branch" are might be more tricky than it seems, e.g. what to do with tags?

Refs for branches and tags are maintained separately in the .git/refs directory. Branches are in .git/refs/heads, tags are in .git/refs/tags. This should make it quite easy to detect all branches, I think, but maybe I'm missing something?

[jp7677]

I'm not so sure about the * wildcard, because I'm afraid this will interfere with globbing functionality of the shell you're executing the command in.

I don't know exactly how the current branch magic works, but I guess when introducing a wildcard, we should not pass this wildcard just to the shell, but evaluate the branches in our code. (assuming that I understood your comment correctly)

I think we should always bail out if one branch fails.

That would mean that branches need to be sane at every moment in time. Looking at my own work flow, sometimes I do create branches just to play/experiment or to push intermediate results (draft or WIP). Those branches will thus prevent valid changes on master/main to appear on the generated site in a CI scenario.

I agree with regard to dirty working spaces and branch/tags. That said, not touching existing working spaces results in not building other branches for the initial scenario where the cloning has already happened by GitHub actions. May be the GitHub action needs to be setup without cloning, not sure what is possible there?

[dirkgroot]

I don't know exactly how the current branch magic works, but I guess when introducing a wildcard, we should not pass this wildcard just to the shell, but evaluate the branches in our code. (assuming that I understood your comment correctly)

What I meant is if you would issue a command like structurizr-site-generatr generate-site --git-url [...] --branches * -w workspace.dsl in your terminal, the shell will expand * with all files in the current directory, resulting in Too many arguments! Couldn't process argument Dockerfile! (where Dockerfile is a file in the current directory). This can be preventing by enclosing the * in double quotes, but it's still a bit tricky...

[jp7677]

ah, now i get your point ;), Yes, this is indeed a valid risk.

[qtzar]

Closing this discussion as the feature has now been added and will be released soon.