Don't Repeat Yourself #107
Conversation
|
Excellent, thank you. There are so many good syntax fixes here! The draft of the DRY looks like the right general direction. I would like to try out some options during the next few days... For example, my intuition is there may be some value to having the directory also contain a file that is ready to copy/paste into a user's own file, that has the alias keyword and definition, and also comments/documentation. This tends to make it really easy to share one alias with someone. Could there be advantage to naming that file the same as the actual alias (e.g. "git-foo.txt") rather than a file name that is the same across all aliases? An advantage that comes to mind is making it easy for a user to download a few aliases, and be able to distinguish the downloaded files via the file names. Users have asked for this, for some of the more-complex aliases such as Lots to think about. Thank you for motivating this! |
The syntax fixes are actually what's #106 is about. This is just ahead of #106 :)
Yeah, I also had this in mind.
Some people seem to use
|
|
Great! Your What do you think about putting the new *.gitconfig files into their directories? Such as: Upside is it makes directory navigation easier and cleaner. Downside is the URL is repetitive. I slightly favor the upside, because it feels to me like the directory will be the one place someone will have to look. To me, this looks like helpful encapsulation. Am I viewing it correctly that the big open question to solve is where the comments and examples go? |
I guess so. If I understand correctly we agree on the following:
We still need to refine (4.). I think that # git ${ALIAS_NAME}
\```gitconfig
${ALIAS_NAME} = ${ALIAS_DEFINTION}
\```
${DESCRIPTION}(Note that the backslash is only there since I am also writing this comment in markdown...) In the simplest case, Also note that we should be able to generate ${DESCRIPTION} # here, the description must be prepended with `#` per line, to get a comment.
${ALIAS_NAME} = ${ALIAS_DEFINITION}Is it sufficient to have the same description in Also, where do the "TODOs" go? I'd say temporarily into One other thing I don't understand is why there is |
Yes.
Yes. Open question of where to put corresponding documentation for comments, examples, credit, references, etc.?
Yes. Open question of documentation as above?
Yes, except minor correction that the output file is
Yes. Perhaps the name
Yes that's good. I don't have any more requirements for the content for each specific alias. As you've seen, there are groups of related aliases, and currently I'm doing copy/paste for the content for these, e.g. "Related aliases" at the bottom of a markdown documentation page. Beyond this commit, it could be good to have a way to manage these.
Yes.
Yes.
Mostly yes. The most-important difference is there are some chunks of the top-level file that are written to be easy for teams to discuss and adopt. For example, there's currently an opening section of tiny shortcuts that are so simple that there is no per-alias comment. This opening section is what convinces the majority of teams to try the aliases. I.e. the file is deliberately organized to make it easy for teams to understand and adopt. In practice, this shortcut section is the #1 reason teams say yes to trying gitalias.
Yes.
GitHub lock-in has been problematic in practice for some large customers. A file
Yes, that's a workaround just for GitHub's problem. The Unfortunately, GitHub tooling renders the file This overall issue has a long history of causing errors in many projects, and with documentation systems, customer internal search engines, etc Every year or so, I try to check to see if the situation has improved. My understanding is GitHub staff wants the file name One workaround is a symlink. Another potential workaround is Perhaps there are other approaches? |
Sorry, but I am not sure I understand your question. Regular, i.e. non-shell, aliases do not allow comments as part of the alias. Shell-aliases do allow comments, like any other shell script. General comments on the alias, examples, credit, references go in Apart from that, there would be no place to add any additional information.
Again, I do not understand exactly what you mean.
OK.
I like
Right. Maybe we can use
Right. Without adding any exceptions to our design so far, these very short aliases would have an empty When it comes to sorting, I'd say we can use
OK.
Alright. I do get that there are outside constraints, but to be honest I don't want to continue discussing it here and now. Absolutely no problem with the discussion per se, but I think just want to accept that |
|
I think I have enough information to prototype generation of |
Sorry, I was unclear. What I'm imagiging is something like these pseudocode samples, that have a block comment with ilne 1 alias title (e.g. "git-foo"), line 3 as a one-line sentence summary (e.g. "Foo because bar."), then examples, discussion, etc. File [alias]
# git-pr
#
# Pull with rebase in order to provide a cleaner, linear, bisectable history
#
# … Help and commentary as needed …
# … Some aliases have a bunch of help and discussion …
# … Various thanks, credits, reference links, etc. …
pr = pull --rebase
Yes good. We understand each other.
Good idea. Yes.
Yes that makes sense to me.
I'm unsure if I'm understanding you here. Are saying akin to a table-of-contents file and/or an ordered manifest file? This sounds fine to me. The purpose is to ensure grouping of related aliases, such as the one-letter shorthands, the the log-related aliases, the topic branch aliases, the maintenance aliases such as For what it's worth, changes to alias ordering are extremely rare. The typical change is inserting one alias. The rare change is inserting a group of aliases, such as the new worktree aliases in progress in the other merge request.
I agree with you about this one. <3 Thank you for being understanding of the quirks! :-) |
First draft for generating
/gitalias.txtfrom/**/alias.{sh,txt}.